We are happy to announce a major release of the MySensors library to 2.0.0!
For details, see here.
Doxygen links on the master github frontpage are not working. These are the correct links:
master development

Signing support has now been implemented and is available from release 1.5 of the MySensors library.
From version 2.0.0, all documentation is managed using doxygen, and you find the most current documentation here for releases and here for development branch.
You can find the signing documentation under "modules" and "MySensors internal APIs and functionalities > MySigning".

In an effort to normalize the technical playing field for all forum members I will describe what this means, and why it is important. And I will also briefly touch on the generic concept of authentication and verification, motivate the need for this (and explain why encryption is not part of this) and go on to explain the architecture used for MySensors and how to enable and use this new feature.

Background and concepts

Suppose two participants, Alice and Bob, wants to exchange a message. Alice sends a message to Bob. In MySensors “language” Alice could be a gateway and Bob an actuator (light swich, electronic lock, etc). But to be generic, we will substitute the term “gateway” with Alice and a “node” with Bob (although the reverse relationship is also supported).

Alice sends a message to Bob. This message can be heard by anyone who wants to listen (and also by anyone that is within “hearing” distance). Normally, this is perhaps not a big issue. Nothing Alice says to Bob may be secret or sensitive in any way.
However, sometimes (or perhaps always) Bob want to be sure that the message Bob receives actually came from Alice. In cryptography, this is known as authenticity. Bob need some way of determining that the message is authentic from Alice, when Bob receives it. This prevent an eavesdropper, Eve, to trick Bob into thinking it was Alice that sent a message Eve in fact transmitted. Bob also need to know how to determine if the message has been repeated. Eve could record a message sent by Alice that Bob accepted and then send the same message again. Eve could also in some way prevent Bob from receiving the message and delay it in order to permit the message to arrive to Bob at a time Eve chooses, instead of Alice. Such an attack is known as a replay attack.
Authenticity permits Bob to determine if Alice is the true sender of a message.

It can also be interesting for Bob to know that the message Alice sent has not been tampered with in any way. This is the integrity of the message. We now introduce Mallory, who could be intercepting the communication between Alice and Bob and replace some parts of the message but keeping the parts that authenticate the message. That way, Bob still trusts Alice to be the source, but the contents of the message was not the content Alice sent. Bob needs to be able to determine that the contents of the message was not altered after Alice sent it.
Mallory would in this case be a man-in-the-middle attacker.
Integrity permits Bob to verify that the messages received from Alice has not been tampered with.
This is achieved by adding a signature to the message, which Bob can inspect to validate that Alice is the author.

The signing scheme used, needs to address both these attack scenarios. Neither Eve nor Mallory must be permitted to interfere with the message exchange between Alice and Bob.

The key challenge to implementing a secure signing scheme is to ensure that every signature is different, even if the message is not. If not, replay attacks would be very hard to prevent.
One way of doing this is to increment some counter on the sender side and include it in the signature. This is however predictable.
A better option would be to introduce a random number to the signature. That way, it is impossible to predict what the signature will be. The problem is, that also makes it impossible for the receiver (Bob) to verify that the signature is valid.
A solution to this is to let Bob generate the random number, keep it in memory and send it to Alice. Alice can then use the random number in the signature calculation and send the signed message back to Bob who can validate the signature with the random number used.
This random number is in cryptography known as a nonce or salt.

However, Mallory might be eavesdropping on the communication and snoop up the nonce in order to generate a new valid signature for a different message. To counter this, both Alice and Bob keep a secret that only they know. This secret is never transmitted over the air, nor is it revealed to anybody. This secret is known as a pre-shared key (PSK).

If Even or Mallory are really sophisticated, he/she might use a delayed replay attack. This can be done by allowing Bob to transmit a nonce to Alice. But when Alice transmits the uniquely signed message, Mallory prevents Bob from receiving it, to a point when Mallory decides Bob should receive it. An example of such an attack is described here.
This needs to be addressed as well, and one way of doing this is to have Bob keep track of time between a transmitted nonce and a signed message to verify. If Bob is asked for a nonce, Bob knows that a signed message is going to arrive “soon”. Bob can then decide that if the signed message does not arrive within a predefined timeframe, Bob throws away the generated nonce and thus makes it impossible to verify the message if it arrives late.

The flow can be described like this:

The benefits for MySensors to support this are obvious. Nobody wants others to be able to control or manipulate any actuators in their home.

Why encryption is not part of this

Well, some could be uncomfortable with somebody being able to snoop temperatures, motion or the state changes of locks in the environment. Signing does not address these issues. Encryption is needed to prevent this.
It is my personal standpoint that encryption should not be part of the MySensors “protocol”. The reason is that a gateway and a node does not really care about messages being readable or not by “others”. It makes more sense that such guarantees are provided by the underlying transmission layer (RF solution in this case). It is the information transmitted over the air that needs to be secret (if user so desires). The “trust” level on the other hand needs to go all the way into the sketches (who might have different requirements of trust depending on the message participant), and for this reason, it is more important (and less complicated) to ensure authenticity and integrity at protocol-level as message contents is still readable throughout the protocol stack. But as soon as the message leaves the “stack” it can be scramble into “garbage” when transmitted over the air and then reassembled by a receiving node before being fed in “the clear” up the stack at the receiving end.

There are methods and possibilities to provide encryption also in software, but if this is done, it is my recommendation that this is done after integrity- and authentication information has been provided to the message (if this is desired). Integrity and authentication is of course not mandatory and some might be happy with only having encryption to cover their need for security. I, however, have only focused on integrity and authenticity while at the same time keeping the current message routing mechanisms intact and therefore leave the matter of secrecy to be implemented in the “physical” transport layer. With the integrity and authenticity handled in the protocol it ought to be enough for a simple encryption (nonce-less AES with a PSK for instance) on the message as it is sent to the RF backend. Atmel does provide such circuits as well but I have not investigated the matter further as it given the current size of the ethernet gateway sketch is close to the size limit on an Arduino Nano, so it will be difficult to fit this into some existing gateway designs.
Also it is worth to consider that the state of a lock can just as readily be determined by simply looking at the door in question or attempting to open it, so obfuscating this information will not necessarily deter an attacker in any way.
Nevertheless, I do acknowledge that people find the fact that all information is sent “in the clear” even if it require some technical effort for an intruder to obtain and inspect this information. So I do encourage the use of encrypting transport layers.
This is however not covered by this topic nor my implementation.

How this is done

There exist many forms of message signature solutions to combat Eve and Mallory.
Most of these solutions are quite complex in term of computations, so I elected to use an algorithm that an external circuit is able to process. This has the added benefit of protecting any keys and intermediate data used for calculating the signature so that even if someone were to actually steal a sensor and disassembled it, they would not be able to extract the keys and other information from the device.
A common scheme for message signing (authenticity and integrity) is implemented using HMAC which in combination with a strong hash function provides a very strong level of protection.
The Atmel ATSHA204A is a low-cost, low-voltage/current circuit that provides HMAC calculation capabilities with SHA256 hashing which is a (currently) virtually unbreakable combination. If SHA256 were to be hacked, a certain cryptocurrency would immediately be rendered worthless.
The ATSHA device also contain a random number generator (RNG) which enables the generation of a good nonce, as in, non-predictable.
As I acknowledge that some might not want to use an additional external circuit, I have also implemented a software version of the ATSHA device, capable of generating the same signatures as the ATSHA device does. Because it is pure-software however, it does not provide as good nonces (it uses the Arduino pseudo-random generator) and the HMAC key is stored in SW and is therefore readable if the memory is dumped. It also naturally claims more flash space due to the more complex software. But for indoor sensors/actuators this might be good enough for most people.

How to use this

Before we begin with the details, I just want to emphasize that signing is completely optional and although it is enabled by default, it will use a default backend that does not require signing and does not enforce signature checks. However, if you really do not want any additional "cost" in program space related to signing, you can disable MY_SIGNING_FEATURE in MyConfig.h.

Firstly, you need to make sure MY_SIGNING_FEATURE is enabled in MyConfig.h. You then select which backend to use by passing the appropriate handle when constructing the MySensor object. The handle is passed as the third argument (example here uses the real ATSHA without whitelisting):

#include <MySigningAtsha204.h>

MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile
MySigningAtsha204 signer; // Select HW ATSHA signing backend

MySensor gw(radio, hw, signer);

If the software equivalent if the ATSHA is desired instead do

#include <MySigningAtsha204Soft.h>

MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile

// Change the soft_serial value to an arbitrary value for proper security
uint8_t soft_serial[SHA204_SERIAL_SZ] = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09};
MySigningAtsha204Soft signer(true, 0, NULL, soft_serial);  // Select SW ATSHA signing backend

MySensor gw(radio, hw, signer);

It is legal to mix MySigningAtsha204 and MySigningAtsha204Soft backends in a network. They work together.

Secondly, you need to verify the configuration for the backend. Currently, only MySigningAtsha204 and MySigningAtsha204Soft backends have a specific configuration.
For MySigningAtsha204 it is the pin the device is connected to. In MyConfig.h there are defaults for sensors and gateways which you might need to adjust to match your personal build. The setting is defined using MY_ATSHA204_PIN and the default is to use pin A3.
For MySigningAtsha204Soft, an unconnected analog pin is required to set a random seed for the pseudo-random generator. It is important that the pin is floating, or the output of the pseudo-random generator will be predictable, and thus compromise the signatures. The setting is defined using MY_RANDOMSEED_PIN and the default is to use pin A7.

Thirdly, if you use the MySigningAtsha204Soft backend, you need to create/set a HMAC key to use. This key is 32 bytes wide and should be an arbitrarily chosen value. A string is OK, but as this key never needs to be “parsed” a completely random number is recommended. The key is stored in our sketch and is passed when constructing the MySigningAtsha204Soft object.

If you use the “real” ATSHA204A, before any signing operations can be done, the device needs to be personalized. This can be a daunting process as it involves irreversibly writing configurations to the device, which cannot be undone. I have however tried to simplify the process as much as possibly by creating a helper-sketch specifically for this purpose in libraries/MySensors/examples/Sha204Personalizer/sha204_personalizer.ino

The process of personalizing the ATSHA204A involves

• Writing and locking chip configuration
• (optionally) Generating and (mandatory) writing HMAC key
• (optionally) Locking data sections

First execute the sketch without modifications to make sure communications with the device can be established. It is highly recommended that the first time this is done, a device with serial debug possibilities is used.
When this has been confirmed, it is time to decide what type of personalization is desired.
There are a few options here.
Firstly, enable LOCK_CONFIGURATION to allow the sketch to lock the chip configuration. The sketch will write the default settings to the chip because these are fine for our purposes. This also enables the RNG which is required to allow the sketch to automatically generate a PSK if this is desired.
Now it is possible to execute the sketch to lock the configuration and enable the RNG.
Next step is to decide if a new key should be generated or an existing key should be stored to the device. This is determined using USER_KEY_DATA, which, if defined, will use the data in the variable user_key_data.
If USER_KEY_DATA is disabled, the RNG will be used to generate a key. This key obviously need to be made available to you so you can use it in other devices in the network, and this key is therefore also printed on the serial console when it has been generated.
The key (generated or provided) will be written to the device unless SKIP_KEY_STORAGE is set. As long as the data zone is kept unlocked the key can be replaced at any time. However, Atmel suggests the data region to be locked for maximum security. On the other hand, they also claim that the key is not readable from the device even if the data zone remains unlocked so the need for locking the data region is optional for MySensors usage.
For devices that does not have serial debug possibilities, it is possible to set SKIP_UART_CONFIRMATION, but it is required to set USER_KEY_DATA if this option is enabled since a generated and potentially unknown key could be written to the device and thus rendering it useless (if the data zone is also locked).
For devices with serial debug possibilities it is recommended to not use SKIP_UART_CONFIRMATION as the sketch without that setting will ask user to send a ‘space’ character on the serial terminal before any locking operations are executed as an additional confirmation that this irreversible operation is done. However, if a number of nodes are to undergo personalization, this option can be enabled to streamline the personalization.
This is a condensed description of settings to fully personalize and lock down a set of sensors (and gateways):
Pick a “master” device with serial debug port.
Set the following sketch configuration of the personalizer:
Enable LOCK_CONFIGURATION
Disable LOCK_DATA
Enable SKIP_KEY_STORAGE
Disable SKIP_UART_CONFIGURATION
Disable USER_KEY_DATA

Execute the sketch on the “master” device to obtain a randomized key. Save this key to a secure location and keep it confidential so that you can retrieve it if you need to personalize more devices later on.
Now reconfigure the sketch with these settings:
Enable LOCK_CONFIGURATION
Enable LOCK_DATA (if you are sure you do not need to replace/revoke the key, this is the most secure option to protect from key readout according to Atmel, but they also claim that key is not readable even if data region remains unlocked from the slot we are using)
Disable SKIP_KEY_STORAGE
Enable SKIP_UART_CONFIGURATION
Enable USER_KEY_DATA
Put the saved key in the user_key_data variable.

Now execute the sketch on all devices you want to personalize with this secret key. That’s it. Personalization is done and the device is ready to execute signing operations which are valid only on your personal network.

In case you want to be able to "whitelist" trusted nodes (in order to be able to revoke them in case they are lost) you also need to take note of the serial number of the ATSHA device. This is unique for each device. The serial number is printed in a copy+paste friendly format by the personalizer for this purpose.

Signing in the MySensors network is driven from the receiving nodes. That means, if a node require signing it will inform the gateway of this. To instruct a node to require signing by the gateway, provide a suitable backend to the library constructor. Both MySigningAtsha204 and MySigningAtsha204Soft backends will by-default require signing when used.
The default constructors for these backends can be overridden to disable signing requirements if the node does not require signed messages but still need the ability to verify messages (like a gateway).

Example for a node that uses ATSHA and require signing:

#include <MySigningAtsha204.h>
MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile
MySigningAtsha204 signer; // Select ATSHA204A physical signing circuit
MySensor gw(radio, hw, signer);

Example for a gateway that uses ATSHA signing in software and do not require signing from nodes:

#include <MySigningAtsha204Soft.h>
MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile
uint8_t soft_serial[SHA204_SERIAL_SZ] = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09};
MySigningAtsha204Soft signer(false, 0, NULL, soft_serial);  // Select ATSHA204A software signing backend
MySensor gw(radio, hw, signer);

If a node does require signing, any unsigned message sent to the node will be rejected.
This also applies to the gateway. However, the difference is that the gateway will only require signed messages from nodes it knows in turn require signed messages.
A node can also inform a different node that it expects to receive signed messages from it. This is done by transmitting an internal message of type I_REQUEST_SIGNING and provide a boolean for payload, set to true.
All nodes and gateways in a network maintain a table where the signing preferences of all nodes are stored. This is also stored in EEPROM so if the gateway reboots, the nodes does not have to retransmit a signing request to the gateway for the gateway to realize that the node expect signed messages.
Also, the nodes that do not require signed messages will also inform gateway of this, so if you reprogram a node to stop require signing, the gateway will adhere to this as soon as the new node has presented itself to the gateway.

The following sequence diagram illustrate how messages are passed in a MySensors network with respect to signing:

None of this activity is “visible” to you (as the sensor sketch implementor). All you need to do is to set your preferences in MyConfig.h, depending on chosen backend, do personalization or key configurations and set the requestSignatures parameter to true. That is enough to enable protection from both Eve and Mallory in your network (although because of the lack of encryption, Eve can eavesdrop, but not do anything about, your messages).

Whitelisting and node revocation

Consider the situation when you have set up your secure topology. We use the remotely operated garage door as an example:

• You have a node inside your garage (therefore secure and out of reach from prying eyes) that controls your garage door motor. This node require signing since you do not want an unauthorized person sending it orders to open the door.
• You have a keyfob node with a signing backend that uses the same PSK as your door opener node.

In this setup, your keyfob can securely transmit messages to your door node since the keyfob will sign the messages it sends and the door node will verify that these were sent from a trusted node (since it used the correct PSK). If the keyfob does not sign the messages, the door node will not accept them.

One day your keyfob gets stolen or you lost it or it simply broke down.

You know end up with a problem; you need some way of telling your door node that the keyfob in question cannot be trusted any more. Furthermore, you maybe locked the data region in your door nodes ATSHA device and is not able to revoke/change your PSK, or you have some other reason for not wanting to replace the PSK. How do you make sure that the "rogue" keyfob can be removed from the "trusted chain"?

The answer to this is whitelisting. You let your door node keep a whitelist of all nodes it trusts. If you stop trusting a particular node, you remove it from the nodes whitelist, and it will no longer be able to communicate signed messages to the door node.

This is achieved by 'salting' the signature with some node-unique information known to the receiver. In the case of ATSHA204A this is the unique serial number programmed into the circuit. This unique number is never transmitted over the air in clear text, so Eve will not be able to figure out a "trusted" serial by snooping on the traffic.
Instead the value is hashed together with the senders NodeId into the HMAC signature to produce the final signature. The receiver will then take the originating NodeId of the signed message and do the corresponding calculation with the serial it has stored in it's whitelist if it finds a matching entry in it's whitelist.

Whitelisting is an optional alternative because it adds some code which might not be desirable for every user. So if you want the ability to provide and use whitelists, as well as transmitting to a node with a whitelist, you need to enable MY_SECURE_NODE_WHITELISTING in MyConfig.h
The whitelist is provided when constructing the signing backend as follows (example is a node that require signing as well):

#include <MySigningAtsha204.h>
MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile
#ifdef MY_SECURE_NODE_WHITELISTING
whitelist_entry_t node_whitelist[] = {
  { .nodeId = 55, // Just some value, this need to be changed  to the NodeId of the trusted node
    .serial = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09} } // This need to change to the serial of the trusted node
};
MySigningAtsha204 signer(true, 1, node_whitelist);  // Select ATSHA204A software signing backend with one entry in the whitelist
#else
MySigningAtsha204 signer;  // Select ATSHA204A software signing backend
#endif
MySensor gw(radio, hw, signer);

The "soft" backend of course also support whitelisting. However, since it does not contain a unique identifier, you have to provide an additional constructor argument when you enable whitelisting as illustrated in this example:

#include <MySigningAtsha204Soft.h>
MyTransportNRF24 radio;  // NRFRF24L01 radio driver
MyHwATMega328 hw; // Select AtMega328 hardware profile
#ifdef MY_SECURE_NODE_WHITELISTING
// Change the soft_serial value to an arbitrary value for proper security
uint8_t soft_serial[SHA204_SERIAL_SZ] = {0x09,0x08,0x07,0x06,0x05,0x04,0x03,0x02,0x01};
whitelist_entry_t node_whitelist[] = {
  { .nodeId = 55, // Just some value, this need to be changed to the NodeId of the trusted node
    .serial = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09} } // This need to change to the serial of the trusted node
};
MySigningAtsha204Soft signer(true, 1, node_whitelist, soft_serial);  // Select ATSHA204A software signing backend with one entry in the whitelist and our unique serial
#else
MySigningAtsha204 signer;  // Select ATSHA204A software signing backend
#endif
MySensor gw(radio, hw, signer);

For a node that should transmit whitelisted messages but not receive whitelisted messages, you can simply skip the whitelist arguments (1 and node_whitelist above). For the "soft" backend, you can set these to 0 and NULL since you then need to provide the soft_serial buffer.

It is important to emphasize that you do not have to provide a whitelist that has entries for all nodes that transmit signed messages to the node in question. You only need to have entries for the nodes that in turn have enabled MY_SECURE_NODE_WHITELISTING. Nodes that does not have this option enabled can still transmit "regular" signed messages as long as they do not match a NodeId in the receivers whitelist.

The technical stuff

How are the messages actually affected by the signing?
The following illustration shows what part of the message is signed, and where the signature is stored:

The first byte of the header is not covered by the signature, because in the network, this byte is used to track hops in the network and therefore might change if the message is passing a relay node. So it cannot be part of the signature, or the signature would be invalid when it arrives to its destination. The signature also carries a byte with a signing identifier to prevent false results from accidental mixing of incompatible signing backends in the network. Thus, the maximum size for a payload is 29-7 bytes. Larger payloads are not possible to sign. Another thing to consider is that the strength of the signature is inversely proportional to the payload size.

As for the ATSHA204SOFT backend, it turns out that the ATSHA does not do “vanilla” HMAC processing. Fortunately, Atmel has documented exactly how the circuit processes the data and hashes thus making it possible to generate signatures that are identical to signatures generated by the circuit.

The signatures are calculates in the following way:

Exactly how this is done can be reviewd in the source for the ATSHA204SOFT backend and the ATSHA204A datasheet.
In the MySensors protocol, the following new internal messagetypes has been added for handling signature requirements and nonce requests:
I_REQUEST_SIGNING
I_GET_NONCE
I_GET_NONCE_RESPONSE

Also, the version field in the header has been reduced from 3 to 2 bits in order to fit a single bit to indicate that a message is signed.

Known limitations

It is very important to emphasize that with the current implementation of message signing, OTA firmware updates are transmitted unsigned. In other words, it is technically possible for Mallory to reset a node by cutting power or some other attack, spoof a gateway and push his/her own custom firmware to the node even if the old sketch was requiring signing. The current architecture of the OTA solution prevents signing support from being implemented in the bootloader due to size constraints.
It is still possible to use OTA bootloader with a signing gateway and node, but it is important to understand this potentially provides an attack vector for compromising the security of the node.
Also, due to the limiting factor our our Arduino nodes, the use of diversified keys is not implemented. That mean that all nodes in your network share the same PSK (at least the ones that are supposed to exchange signed data). It is important to understand the implications of this, and that is hopefully covered in the "Typical usecases" chapter below.
Also be reminded that the strength of the signature is inversely proportional to the size of the message. The larger the message, the weaker the signature.

Typical usecases

"Securely located" in this context mean a node which is not physically publicly accessible. Typically at least your gateway.
"Public" in this context mean a node that is located outside your "trusted environment". This includes sensors located outdoors, keyfobs etc.

Securely located lock

You have a securely located gateway and a lock somewhere inside your "trusted environment" (e.g. inside your house door, the door to your dungeon or similar).
You should then keep the data section of your gateway and your lock node unlocked. Locking the data (and therefore the PSK) will require you to replace at least the signing circuit in case you need to revoke the PSK because some other node in your network gets compromised.

Patio motion sensor

Your gateway is securely located inside your house, but your motion sensor is located outside your house. You have for some reason elected that this node should sign the messages it send to your gateway.You should lock the data (PSK) in this node then, because if someone were to steal your patio motion sensor, they could rewrite the firmware and spoof your gateway to use it to transmit a correctly signed message to your secure lock inside your house. But if you revoke your gateway (and lock) PSK the outside sensor cannot be used for this anymore. Nor can it be changed in order to do it in the future. You can also use whitelisting to revoke your lost node.
This is an unlikely usecase because it is really no reason to sign sensor values. If you for some reason want to obfuscate sensor data, encryption is a better alternative.

Keyfob for garage door opener

Perhaps the most typical usecase for signed messages. Your keyfob should be totally locked down. If the garage door opener is secured (and it should be) it can be unlocked. That way, if you loose your keyfob, you can revoke the PSK in both the opener and your gateway, thus rendering the keyfob useless without having to replace your nodes. You can also use whitelisting to revoke your lost keyfob.

Board releases:

• Version 1.1 [purchase](the 5x5 board as sent to manufacturing, HW verification NOT done)
• Version 1.0 [purchase](contain multiple issues, NOT recommended to use, does only cotain 5x5 layout and the release is signed with my old (revoked) PGP key)

I designed this board as a host for the hardware I have collected so far.
I have made three layouts of the board; one “low cost” 5x5 cm board (allows the cheapest option at Dirt Cheap Dirty Boards and two layouts tailored for two Superbat boxes. BOX-2252 and LE-BOX-0028.

Feature list (short version):

• Accepts Arduino Pro Mini 3.3V in all variants I am familiar with
• Supports both NRF24 and RFM69 but not simultaneously due to lack of available IO
• Supports MYSX 1.0 to 1.5 daughterboards
• Supports both “conventional” battery measurement and a low-power variant of it
  • Instead of a dual resistor divider, I use a potentiometer. That way, any analog reference level can be used, and resolution can be tuned against any expected value of battery voltage
• Two different regulators can be used (depending on input voltage)
  • 12V input or 4.2V input (step-up)
    • 4.2V regulator can be programmatically bypassed for low power operation when battery is high enough for all circuitry. Two options exist; TI TPS61221 and TI TPS61097A, both 3.3V fixed versions (no support for variable voltage versions)
• 6 different ways of powering the board
  • DC socket
  • Battery wires
  • JST socket (LiPo cells)
  • CR123 socket
  • 24.5mm coincell
  • MYSX daughterboard Vraw supply
• MYSX 3.3V power can be programmatically switched off
• ATSHA204A HW authentication/signing
• 3 dedicated switchable 3.3V/GND rail pins for discrete sensors
• Onboard SI7021 temp/hum sensor
• AVR ISP programming header
• External SPI flash for OTA

Due to limited available IO and to support various use cases some aspects of the board is configurable using jumpers:

• JP1 - Serves as current measurement tap from on-board power connectors. Has to be shorted if on-board power connectors are used.
• JP2 - Selects 3.3V regulator. Pos 1-2 for 4.2V input (max) and pos 2-3 for 12V input (max)
• JP3 - Sort to bypass regulators and tie on-board power connectors directly to 3.3V net
• JP4 - Short to skips the low-power battery sampling option. This will cause a continuous power drain on the batteries through a 1M Ohm potentiometer.
• JP5 - Short to skip the switch for MYSX 3.3V rail. MYSX 3.3V rail will be “permanently on”.
• JP6 - Short to cause MYSX_D10_A4 signal to be used to set low-voltage 3.3V regulator in bypass mode. This can be used if battery voltage is high enough to drive all circuitry without being boosted at the potential expense of the MYSX_D10_A4 pin usage of a daughterboard. JP6 serves as a mean to permit MYSX_D10_A4 to behave according to MYSX specifications if left open (at the corresponding expense of not being able to set regulator in bypass mode).
• JP7 - Serves as current measurement tap for off-board power connector through MYSX. Has to be shorted if off-board power connector is used.
• JP8 - Selects INT1 interrupt source. Pos 1-2 for MYSX_D3_INT and pos 2-3 for RF board.
• JP9 - Selects SPI SS destination. Pos 1-2 for NRF24 and pos 2-3 for RFM69.
• JP10 - Short to enable MYSX_D9_A3 to be used to take a low-power battery sample. If enabled, analog measurement of a daughterboard on MYSX_D9_A3 might not work as expected.

Feature list (the somewhat more comprehensive version):

• Any Arduino Pro Mini with A6 and A7 pins available should fit this board (A6 and A7 is required to comply with MYSX specifications.
• Although the board can take both NRF24 and RFM69 at the same time mounted, they share pin for SPI chip select, so they cannot be used simultaneously (unless you patch the board to re-route one of the chip selects to a different Arduino pin and make the necessary SW modifications)
• Support the MySensors Expansion port (MYSX) in all versions up to 1.5. MYSX specifications is available here. Depending on what battery sockets are mounted on the board, the MYSX connector may have to be “raised” so a daughterboard can fit in some of the layouts of the board.
• Flexible options for battery measurement:
  • Voltage divider is implemented using a potentiometer (1M@RV1) which makes it possible to tune the sample voltage to optimize measurement range.
  • JP4 can be shorted to connect battery net directly to potentiometer (which in turn is connected to Arduino pin A0). A footprint for an optional decoupling capacitor is available at C8 to smooth the sample value. It is not recommended to use C8 if low-power sampling option is used.
  • With JP4 open, battery samples are taken by momentarily driving MYSX_D9_A3 low (Arduino pin A1). When sample is taken, MYSX_D9_A3 is set high again, which prevents continuous drain of battery through RV1. This assumes JP10 is shorted. If a daughterboard is connected that uses MYSX_D9_A3, analog samples taken on that pin might be affected by the 0.1uF capacitor (C9) when JP10 is shorted.
• Depending of power source used, two regulator options are available.
  • For “high” voltage sources a LDO provides the regulated 3.3V voltage. Maximum accepted voltage is 12V. This is enabled by shorting JP2 pos 2-3.
  • For “low” voltage sources a step-up voltage regulator provides the 3.3V voltage. Maximum accepted voltage is 4.2V. This is enabled by shorting JP2 pos 1-2. The step-up voltage regulator also implements a pass-through option in which the regulator is turned off and the input voltage is fed right through it. The pass-through is enabled by driving MYSX_D10_A4 low (Arduino pin A2) and shorting JP6. Be aware that this also goes through the MYSX connector, so it is not recommended to use this feature if a daughterboard is connected that uses MYSX_D10_A4. There are two footprints available for this regulator alternative; SC-70 (TI TPS61221) and SOT-23 (TI TPS61097A). Both has to be the 3.3V fixed version since there is no footprints for adjustment-resistors. Also note that these two regulators are mutually exclusive. Do NOT mount them both at the same time.
• All different power source options can be simultaneously mounted (not that it has to be). But on some layouts, the BT4 and BT5 (CR123 and coin cell) connectors one of the BT4 connector legs needs to be filed down if a coin cell battery is to be fitted. But the layout will ensure no shorts are risked. On the 5x5cm board, BT4 and BT5 are omitted due to size constraints.
  The following possibilities exist:
  • DC socket (BOM will use 2.5MM part with center pin being positive and shield ground.
  • Battery wires (or virtually any power source) can be connected to a 2.54mm pitch screw terminal (or soldered directly to the board).
  • A JST (S2B-PH-K-S) connector for LiPo cells (like this or this one).
  • A CR123 socket (not available on 5x5 cm board).
  • A 24.5mm coincell holder capable of accepting up to CR2477 sizes (not available on 5x5 cm board).
  • Vraw supply from a MYSX daughterboard.
• The 3.3V pin of the MYSX connector can be programmatically switched off.
  • To switch off the 3.3V supply pin drive Arduino pin D4 low. Leave it floating to have the 3.3V pin enabled.
• ATSHA204A HW signing is available (uses Arduino pin A3).
• 3 (switchable) 3.3V/GND rail pairs is available to allow discreet mounting of wired sensors (in excess to the pins available on the MYSX connector).
• An onboard SI7021 sensors is connected to the I2C bus to provide rudimentary sensor possibilities on the motherboard itself.
• An onboard AVR ISP programming socket provides the possibility to program a custom bootloader to the Arduino (useful for OTA).
• An external flash is connected to the SPI bus to permit OTA using the Dualoptiboot bootloader.

The schematics and BOMs are done.
Schematics and layouts are all stored here and will be updated from time to time. I will notify in this topic once I have done tape-out and have manufactured the boards. I am somewhat confident on the design of revision 1.1 (with lessons learnt from revision 1.0) so I plan to finish all three boards before I manufacture any one of them.
For the LE-BOX-0028 (the largest box) the layout has all components mounted top side. It also features more silkscreen text for ease of jumper operation and it places the NRF24 module so that it can accommodate a PA/LNA "extended" module and have the antenna exit the box and still be "turnable".
Forum feedback is very welcome!
The designed is licensed under CERN OHL V1.2 and is fully Open Hardware.
And finally, some eye candy (please note that the images might not exactly resemble the actual boards, as I am still making minor tweaks to them)

The 5x5 cm board: (available for purchase at DirtyPCBs)

The BOX-2252 board:

The LE-BOX-0028 board:

Changelog: https://github.com/mysensors/MySensors/releases/tag/2.3.0

Thanks to all GitHub users who contributed to this release:

d00616
flopp999
Kartik Arora
kvoit
Marcelo Aquino
Marco Bakera
Martin Hjelmare
Mikael Falkvidd
Miloslav Kazda
Patrick Fallberg
per1234
seeers
tekka
thucar
Tombula

With the launch of the nice openhardware.io site, design licensing has become more obvious to those who design hardware.
If you decide that you want to license your design, it is important to understand what this means and what (if any) expectations are put on you as licensor (original author of the design) or licensee (user of the license, your own design or someones design you have based your work on).
I have used the CERN OHL v1.2 license and would like to clarify exactly what you need to consider when using that license. If anyone has experience from other Open Hardware licence models, feel free to add to this thread
Also feel free to discuss the CERN license and my interpretation of it.

The CERN OHL v1.2 license is a permissive license. But it still require the licensor to include certain documents with the hardware design files. These expectations are also put on any licencees.
CERN provides a howto to it's licenses where the specifics are documented, but I will try to summarize them here as well:
The licensor/licensee MUST:

• Provide a copy of the CERN license (LICENSE.TXT or LICENSE.PDF or LICENSE.ODT)
• Provide a copy of the CERN license howto (cern_ohl_v_1_2_howto.pdf or cern_ohl_v_1_2_howto.odt)
• Provide a PRODUCT.TXT specifying a contact point where licensees MAY contact the licensor about production and/or distribution of the licensed product if the licensor has indicated a desire to receive this information.
• Provide a CHANGES.TXT where the licensee specifies what modifications has been made to the original design. The licensor may also use this file to provide a changelog of the design.
• Provide the following (I personally use COPYRIGHT.TXT for these)
  • a notice that the hardware design documentation is licensed under the
    CERN OHL v.1.2, possibly with a link to http://ohwr.org/cernohl where
    the licence texts are hosted:
    • “Licensed under CERN OHL v.1.2 or later”
    • “Licensed under CERN OHL v.1.2”
  • a disclaimer of warranties
  • a Documentation Location if you wish to specify one

A licensor MAY:

• Add “Licensed under CERN OHL v.1.2” on top copper layer or silkscreen of PCB

A licensee MUST:

• Keep any existing "Licensed under CERN OHL v.1.2” text on PCB that were on the board the licensee bases the new project on.
• Redistribute the new project under the same license as the original design.
• Keep and maintain a CHANGES.TXT and keep the other copyright/warranty disclaimer notices

So to summarize a bit further. The files you need to keep with your board files are:

• LICENSE.TXT
• cern_ohl_v_1_2_howto.pdf
• PRODUCT.TXT
• CHANGES.TXT
• COPYRIGHT.TXT

For details on the CERN OHL 1.2 license and its usage, see CERN Open Hardware License 1.2 and CERNs FAQ.

We are happy to announce a maintenance release of MySensors library to 1.5.2!

This version is backward compatible with 1.5.1 and contain security related bugfixes and stabilizations:

• Backport of bugfix (#259) in repeaters when forwarding signed messages
• Prevent SecureActuator from accepting ACKs as commands
• Make sure nodes not supporting signing informs gateway
• Fixes addressing bug in _doSign bitfield
• Stabilizes Jenkins

It is recommended that you update all your nodes and gateways if you use message signing.

If you are curious on what features are planned or what fixes are scheduled for the next release or future releases, check out the MySensors projects on Github.

Once library version 2.2 is released (it is currently in beta and available on the development branch on GitHub) users that were using signing or encryption will have to re-do personalization. This is because in 2.2, a checksum has been added to the security data in EEPROM to avoid usage of tampered or accidentally wiped data.
Migrating the data is not complicated as personalization in 2.2 has been rewritten to be simpler to use.

There are a few options here. The simplest is to just re-do personalization from scratch. The new SecurityPersonalizer will guide you through the process. Just execute it unmodified on the device and follow the instructions in the serial console.

If you want to reuse an existing AES or HMAC key , follow this procedure:

1. Execute the SecurityPersonalizer example without any modification on your device. Then take note of the EEPROM contents displayed. It can look something like this:

+------------------------------------------------------------------------------------+
|                                       EEPROM                                       |
+--------+--------+------------------------------------------------------------------+
| Key ID | Status | Key                                                              |
+--------+--------+------------------------------------------------------------------+
| HMAC   | RESET  | FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF |
| AES    | RESET  | FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF                                 |
| SERIAL | RESET  | FFFFFFFFFFFFFFFFFF                                               |
+--------+--------+------------------------------------------------------------------+

1. Copy the HMAC and/or SERIAL and/or AES key (if you use soft signing) or only the AES key (if you use ATSHA204 based signing) and put the values into the following lines in the SecurityPersonalizer.ino file (leave the default values of the HMAC and SERIAL for ATSHA204 based signing):

#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

#define MY_AES_KEY 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00

#define MY_SOFT_SERIAL 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF

1. Uncomment this line:

//#define PERSONALIZE_SOFT

1. Execute the sketch again. Now the data will be rewritten to EEPROM and a checksum will be calculated and stored. For hardware based signing, the "old" HMAC key will remain in use, but the checksum will be updated for the AES key (it will also cover the software HMAC and SERIAL, but they are not used for hardware based signing).

If you do not use, nor plan to use, whitelisting, you can leave the SERIAL value as is, and execute the modified personalizer without further modifications on every devie. If you plan to use (or already use) whitelisting, you need to rewrite the proper serial on all devices as well (users of hardware based signing can ignore this, as the serial of the ATSHA204A is used and is fixed to each device.
Note that if you change the SERIAL compared to what was stored previously, you also will need to update all whitelists that has an entry for that node.

EDIT: Obviously, do NOT copy your ATSHA204A HMAC key and store it in EEPROM. It would negate the benefit of the ATSHA readback protection.

@Eurbaix thank you for your input. You are perfectly correct and the core team is currently discussing alternative approaches for more modern hardware (we have to consider that many users still base their designs on the atmga328p).
But we are looking into implementing some form of PKI based security solution which is in many ways similar to your proposal. I don't have and eta for this yet though. But the new security infrastructure will not support a atmga328p based gw.
Me and @d00616 have been discussing back and forth but we are all limited in time, and implementing security features should be done with care so things take time.

Recently, Google announced that it had succeeded in calculation colliding SHA1 checksums with "reasonable" effort and thus concluding SHA1 is now obsolete and insecure.
MySensors security backend rely on hashes as well, but rest assured there is absolutely no impact for message signatures as they are based on SHA256 and not SHA1.
For details on the cracking, see here.

@lood29 That is correct, assuming the same radio technology is used. Typically, you set up a separate gateway because you want to run a sensor network on a different radio family due to longer distances or similar.

@Yoshu it is possible. When you have two gateways, the networks will be completely isolated so you can run one of them secured while the other is not.
You might need to distinguish the nodes on in your controller by giving them static unique ID:s unless your controller ties the identifiers to each gateway or it might be difficult to determine which mysensors network a node belong to.

@skywatch not really, depending on the algorithm

@Puneit-Thukral yes but for full/specified function, atsha, atmega and any sensor circuitry also need to be operational at that level.

@Puneit-Thukral but will the peripherals still work at that level? No use to lower the BOD if radio/security/sensors stop working at a higher voltage.

Beautiful work

@skywatch that depend on the key size you choose, and how you deploy the implementation (like block chaining and random initialization).
Symmetric ciphers are even quite secure in the quantum world given large enough key sizes.

@skywatch are you implying they recommend AES without an IV or block chaining enhancement? I don't think so

@TheoL AES is not complicated to implement in hardware and the docs suggest they have it but the technical detail is low.

@alexelite they do not, however, state exactly which variant of AES they use. If they do not generate an initialization vector and are not using some block chaining variant, AES is quite weak.