[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 😉

  • @anticimex Heh, then I will invite him/her over for tea congratulate them. And then apply some verbal security 😛

    Can Arduino nano's be updated OTA?

  • Contest Winner

    @alowhum afaik all MySensors capable nodes can be updated OTA with the appropriate bootloader programmed.

  • @anticimex Wow, I didn't know that! I've gotta look into that! cool!

  • Contest Winner

    @alowhum in general where are two options, DualOptiboot which require an external spi flash but is radio agnostic, or the mysbooloader which have no requirements on external components but might need to be recompiled to match your radio settings.

  • Mod

    @anticimex I haven't found dual optiboot for all mysensors boards, but maybe there is a way to make it work and I'm not expert on this

  • Contest Winner

    @gohan hence my comment "in general", and in this sence I believe the board in question is "Can Arduino nano's be updated OTA?" and a nano is atmega328p based, and I believe it supports both bootloader variants. Of course there are some devices that might not support both, or perhaps even any of them, but as most of this discussion relates to resource limited nodes, I think only atmega328p based devices are considered.

  • @alowhum said in [security] Migrating from library version 2.1 to 2.2:

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

    I want to follow upon this: I use RFM69 for transport, they have an encryption engine in hardware. Will there be any difference in time to process the message between using:

    • MY_SECURITY_SIMPLE_PASSWORD with soft encryption done on the ATmega or
    • MY_SIGNING_SIMPLE_PASSWORD and encryption on the RFM or

    If I'm not mistaken a signed message is the full 32 byes anyway, so the actual "airtime" will not change, but maybe the processing time before that will.

    And yes, I am aware of the implications in total system security. But none of my nodes are accessible from the outside of my house. I am not worried about someone reading the contents of my sketch.

  • Contest Winner

    @davidzh If you enable any form of encryption feature, RFM69 will always use the hardware to implement it. So there is no "soft encryption" on RFM69.

  • @anticimex

    Ok clear. Thank you.

  • I've a lot devices with very hard physical access to them. I'm using OTA to change firmware so please describe how to implement "new 2.2 checksum feature" into existing sketch using OTA.

  • Contest Winner

    @bilbolodz Not sure what you mean. Then you have to send personalization sketch OTA and that is really not recommended unless you can do that in a secure way. And the personalizer is not designed to use any radios so you cannot expect to be able to FOTA over a new sketch after personalization. You will have to "bring in" your devices if you want to redo personalization.

  • So it means that (If I want use signing) I'm stuck with mysensors version 2.1?
    I'm not able compile new code (using 2.2) and upload it over OTA because I will loose signing right (without changeing EEPROM content)?
    I think there should be a way to migrate sketch (which is using soft signing) from 2.1 to 2.2 with OTA. Secure sending of keys actually is NOT a problem because (as I understood) new in 2.2 is "only checksum" of EEPROM.
    So if I have "2.1 mysensors library" personalized devices, it's possible to write a program which gets existing data from EEPROM calculate checksum and write it to EEPROM (maybe also migrating other structures if there were other changes). Such sketch can be in safe way transferred via OTA because it doesn't contain any secret information. Then I can upload new (using 2.2 library) version of my sketch and I will have working "2.2" devices without touching it (only OTA). What do you think about it?

    Actually now I've realised (luckily) that in these "hard to get devices" I'm using hardware signing so it should be not a problem (?) 🙂

  • Contest Winner

    @bilbolodz Correct, checksum is on EEPROM data, so you can make a sketch to read it and calculate the checksum yourself. It is all open source so you can just see in the personalizer how it is calculated and replicate that 🙂

  • @anticimex OK maybe I will try but I think it could be a good idea to extend you "migration guide".

  • Contest Winner

    @bilbolodz I disapprove manipulating security related data without the personalizer, so no. You can do it, but I do not endorse it.

  • "Your code your rules" but I'm little surprised with your standpoint.

  • Contest Winner

    @bilbolodz That is fine. But as I have currently no means of verifying, I will not make a update to the guide. If you find a way to do it, you are free to post a guide if other need to make a similar thing.

  • Mod

    @bilbolodz you can still enable signing on gateway and make it optional, so you will have time to update nodes later on.

  • @anticimex I have a question - I have two GWs: one with ATSHA204A and one soft signing.
    I have noticed that when doing #define PERSONALIZE_ATSHA204A, AES key is saved to ATSHA204A and EEPROM. Is this correct? In what case I need a combination of HMAC + AES keys? I do not do whitelisting

  • Contest Winner

    @alexsh1 AES key is never saved to atsha204. It is for encryption and always stored in eeprom.

  • @anticimex Now I got more confused. What keys do I need for atsha204a signing?

  • Contest Winner

    @alexsh1 it is pretty clearly documented. HMAC key is used for signing.

  • @anticimex Sorry, I think I need to re-read documentation. HMAC is for atsha204a signing and AES for encryption, right?

    I am in the process of re-personalising now 🙂

  • Contest Winner

    @alexsh1 correct

  • @anticimex thank you! I set-up singing some time ago and it was working fine, but now I need to revise all that again.

  • Contest Winner

    @alexsh1 it is worth mentioning that if you personalize using 2.2.0, you are free to go back to earlier versions without re doing personalization. It is only when going from 2.1 to 2.2 it has to be redone due to the checksum. Of course, be aware that overwriting the checksum will cause signing to fail again.

  • @anticimex said in [security] Migrating from library version 2.1 to 2.2:

    @alexsh1 Of course, be aware that overwriting the checksum will cause signing to fail again.

    And what has to be done in this case? Re-personalising both GW and a node?

  • Contest Winner

    @alexsh1 re-personalize the node that lost the checksum. Each node (including gw) has a unique personalization and checksum (possibly). Just because one node looses the checksum or gets a mismatch does not mean any other node has the same problem. Everything is stored in eeprom locally.