[security] Migrating from library version 2.1 to 2.2

  • Contest Winner

    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                                                              |
    | 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.

  • I'm looking forward to it become stable! I've been playing with the MY_SIGNING_SIMPLE_PASSWD option and I love it! No more neighbours picking up my data!

  • Contest Winner

    @alowhum Nice to hear. It is stable now.

  • @anticimex I just noticed. Brilliant.

    One thing that I must admit is that I am a little sad that the option I was advocating for about a year ago hasn't really become the option I was hoping for. I suspect that's because I didn't now enough about the difference between signing and encryption, so I was unable to argue well enough what I was looking for.

    Perhaps it can still be a feature request for 2.3: the ability to just put a password at the top of the scripts, and then automatically have encrypted communication on the network. Without signing. As this allows me (and other relative n00bs) to keep using my low-memory Nano's. Because when I tried to implement the current easy option I ran out of memory on almost all the nodes. Which prompted my question about the future of MySensors, and the implied need to upgrade to ARM based devices.

    Again, I know what I am looking for is very poor security. But all I want is to have a really easy pathway (high usability) that lowers the incentive for my neighbour to snoop my network. To go from "hey, look, a node has popped up in Domoticz. Let's see how much power my neighbour uses" to "no node has popped up in Domoticz".

    As I read in the Raspberry gateway thread, creating a simple, encrypted network has in a way become harder. Now all nodes need their own unique key. Hence the sadness, as it seems that upgrading my Nano network to an encrypted state without having to dive into technical details, code generation, signing process and allround effort is actually further away than it was before.

    At least, that's what it seems like. I would be happy to be wrong 🙂

  • Mod

    I'm waiting too to figure out how to get encryption on the rpi gateway

  • Contest Winner

    @gohan have you tried to run mysgw --help?

  • Contest Winner

    @gohan feature toggles for the rPi gateways are documented: https://www.mysensors.org/apidocs/group__RaspberryPiGateway.html

    Regarding the configuration of these features, I don't think there is anything in doxygen for that yet, but you should get a list with mysgw -h or --help

  • Contest Winner

    @alowhum I don't understand what you mean? You have MY_SIGNING_SIMPLE_PASSWD. It enables signing and encryption with out any further configurations. Why would you not want to enable signing? And the password option is also available on the raspberry pi port as documented here: https://www.mysensors.org/apidocs/group__RaspberryPiGateway.html
    The documentation is unclear on the implications of the password flag, but it does enable encryption as well: --my-signing-password=<PASSWORD>

    The general documentation on security details the use of the password flag: https://www.mysensors.org/apidocs/group__SigningSettingGrpPub.html#gaedf8ec407fbde609a520ea0d95da2aac

    I am afraid things can't get much simpler than this.
    If you disagree please elaborate on what you think can be simplified.

    If you for some reason still want (very crappy) encryption only, just change in MyConfig.h to disable the signing flags to not enable them. I don't want to clutter the code with more switches for security. It helps no-one.

  • Hey @Anticimex, thanks for the reply.

    The simple version is really great, don't get me wrong. Absolutely great usability!

    The reason I would like a non-signing option is that it saves a lot of ram. By only using encryption it should be possible to continue using Arduino Nano's as nodes.

    I tried using the MY_SIGNING_SIMPLE_PASSWD option on my Nano's, and the result was that most of my sketches became too big or unstable.

    There just isn't enough space/ram for both hardcore security and sensor libraries.

    Thanks for explaining that I might be able to 'criple' the MY_SIGNING_SIMPLE_PASSWD option. I would suggest that this 'crippling' could perhaps become a feature in itself called "MY_ENCRYPTION_SIMPLE_PASSWD (without the signing).

  • Contest Winner

    @alowhum I will consider it for 2.2.1. But I also need to mind the complexity of the overall functionality. I don't want the security solution to grow more into a beast than it already is.
    The functionality you seek is really simple to implement. But gives even more options for a user to decide on. And although that is for some a great thing it is not for everyone.
    I will see if I can somehow structure the documentation to outline all the configuration settings and try to give each a elaborate description on pros and cons.

  • I can't ask for much more than that. Thanks man!

  • Hardware Contributor


    I did have same issues, with new version, when was in testing stage.

    Try at the top of sketch add these:


    You save a lot of space. All my nodes are on ATMEGA328 and no space issues. Max node with signing + encryption + relay + temp uses 67% of space

  • Contest Winner

    @sineverba there is also a documentation section on this: https://www.mysensors.org/apidocs/group__memorysavings.html

  • Contest Winner

    @sineverba I also believe the signal report flag is reversed nowadays, and is an opt-in feature and not an opt-out feature, using MY_SIGNAL_REPORT_ENABLED which defaults to "off". Hence it is not listed in the memory savings section of the documentation, but the documentation of MY_SIGNAL_REPORT_ENABLED does warn that it adds about 1k of flash use.

  • Hardware Contributor

    @anticimex Ah, I did not know, cause I'm in 2.2.0 rc2 (when something works... don't touch it! 😄 )

  • Contest Winner

    @alowhum check the development branch. Simple password system has been reworked. Also, documentation is updated.

  • @anticimex Awesome!

    So I had a look at the new code, and is this a fair summary?:

    • Simple encryption and simple signing are now two separate functions you can call at the top of your script by adding a line with a password: MY_ENCRYPTION_SIMPLE_PASSWD and MY_SIGNING_SIMPLE_PASSWD.
    • You can also just put "MY_SECURITY_SIMPLE_PASSWD" at the top of your script, and that will do both in one go. This used to be called the MY_SIGNING_SIMPLE_PASSWD option, which also did both.
    MY_SIGNING_SIMPLE_PASSWD only affects signing,
    only affects encryption.
    MY_SECURITY_SIMPLE_PASSWD enable both these flags.

    This is simply wonderful.

    • More choice and flexibility for the end user.
    • Get some simple security on your existing Arduino hardware.

    Thank you so much for this.

  • Contest Winner

    @alowhum you are welcome. Just remember that simple in this context also mean weak. Storing the secrets in the sketch is a huge security implication on targets that does not support readout protection. Atmga328p among others.

  • @anticimex I understand. But if my neighbour has access to the nodes inside my house, then I have a bigger security problem 🙂

  • Contest Winner

    @alowhum right, but if you update your sketches OTA, he can potentially sniff your key OTA as well and then he does not need to enter your house 😉