Encryption, Signing and OTA is there any how-to?



  • Hi,

    i would like to place any sensors at my home, but it should be signed and encrypted. On the website are a lot of builds but noone describes how to setup the encryption and signing.
    OTA too.

    is there something like a how-to or a description how to setup?
    Thanks a lot!


  • Admin

    Check out "The Next Step" here:
    https://www.mysensors.org/about



  • ok, i did read this three times but i dont understand.



  • if i understood it correctly, i have to use the securitypersonalization.ino on the gw. For the first time i upload this code

    /**
     * @def LOCK_CONFIGURATION
     * @brief Uncomment this to enable locking the 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
     */
    #define LOCK_CONFIGURATION
    
    /**
     * @def LOCK_DATA
     * @brief Uncomment this to enable locking the data zone.
     *
     * It is not required to lock data, key cannot be retrieved anyway, but by locking
     * data, it can be guaranteed that nobody even with physical access to the chip,
     * will be able to change the key.
     * @warning BE AWARE THAT THIS PREVENTS THE KEY TO BE CHANGED
     */
    //#define LOCK_DATA
    
    /**
     * @def SKIP_KEY_STORAGE
     * @brief Uncomment this to skip key storage (typically once key has been written once)
     */
    #define SKIP_KEY_STORAGE
    
    /**
     * @def USER_KEY
     * @brief Uncomment this to skip key generation and use @ref user_key_data as key instead.
     */
    //#define USER_KEY
    
    /**
     * @def SKIP_UART_CONFIRMATION
     * @brief Uncomment this for boards that lack UART
     *
     * @b Important<br> No confirmation will be required for locking any zones with this configuration!
     * Also, key generation is not permitted in this mode as there is no way of presenting the generated key.
     */
    //#define SKIP_UART_CONFIRMATION
    
    /**
     * @def USE_SOFT_SIGNING
     * @brief Uncomment this to store data to EEPROM instead of ATSHA204A
     */
    //#define USE_SOFT_SIGNING
    
    /**
     * @def STORE_SOFT_KEY
     * @brief Uncomment this to store soft HMAC key to EEPROM
     */
    //#define STORE_SOFT_KEY
    
    /**
     * @def USER_SOFT_KEY
     * @brief Uncomment this to skip soft HMAC key generation and use @ref user_soft_key_data as HMAC key instead.
     */
    //#define USER_SOFT_KEY
    
    /**
     * @def STORE_SOFT_SERIAL
     * @brief Uncomment this to store soft serial to EEPROM
     */
    //#define STORE_SOFT_SERIAL
    
    /**
     * @def USER_SOFT_SERIAL
     * @brief Uncomment this to skip soft serial generation and use @ref user_soft_serial as serial instead.
     */
    //#define USER_SOFT_SERIAL
    
    /**
     * @def STORE_AES_KEY
     * @brief Uncomment this to store AES key to EEPROM
     */
    //#define STORE_AES_KEY
    
    /**
     * @def USER_AES_KEY
     * @brief Uncomment this to skip AES key generation and use @ref user_aes_key as key instead.
     */
    //#define USER_AES_KEY
    
    

    When its uploaded on first run i will get the AES and HMAC Key, which i have to notice and safe securely.

    Then i have to upload the sketch again with this code:

    /**
     * @def LOCK_CONFIGURATION
     * @brief Uncomment this to enable locking the 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
     */
    #define LOCK_CONFIGURATION
    
    /**
     * @def LOCK_DATA
     * @brief Uncomment this to enable locking the data zone.
     *
     * It is not required to lock data, key cannot be retrieved anyway, but by locking
     * data, it can be guaranteed that nobody even with physical access to the chip,
     * will be able to change the key.
     * @warning BE AWARE THAT THIS PREVENTS THE KEY TO BE CHANGED
     */
    //#define LOCK_DATA
    
    /**
     * @def SKIP_KEY_STORAGE
     * @brief Uncomment this to skip key storage (typically once key has been written once)
     */
    //#define SKIP_KEY_STORAGE
    
    /**
     * @def USER_KEY
     * @brief Uncomment this to skip key generation and use @ref user_key_data as key instead.
     */
    #define USER_KEY
    
    /**
     * @def SKIP_UART_CONFIRMATION
     * @brief Uncomment this for boards that lack UART
     *
     * @b Important<br> No confirmation will be required for locking any zones with this configuration!
     * Also, key generation is not permitted in this mode as there is no way of presenting the generated key.
     */
    #define SKIP_UART_CONFIRMATION
    
    /**
     * @def USE_SOFT_SIGNING
     * @brief Uncomment this to store data to EEPROM instead of ATSHA204A
     */
    //#define USE_SOFT_SIGNING
    
    /**
     * @def STORE_SOFT_KEY
     * @brief Uncomment this to store soft HMAC key to EEPROM
     */
    //#define STORE_SOFT_KEY
    
    /**
     * @def USER_SOFT_KEY
     * @brief Uncomment this to skip soft HMAC key generation and use @ref user_soft_key_data as HMAC key instead.
     */
    //#define USER_SOFT_KEY
    
    /**
     * @def STORE_SOFT_SERIAL
     * @brief Uncomment this to store soft serial to EEPROM
     */
    //#define STORE_SOFT_SERIAL
    
    /**
     * @def USER_SOFT_SERIAL
     * @brief Uncomment this to skip soft serial generation and use @ref user_soft_serial as serial instead.
     */
    //#define USER_SOFT_SERIAL
    
    /**
     * @def STORE_AES_KEY
     * @brief Uncomment this to store AES key to EEPROM
     */
    #define STORE_AES_KEY
    
    /**
     * @def USER_AES_KEY
     * @brief Uncomment this to skip AES key generation and use @ref user_aes_key as key instead.
     */
    //#define USER_AES_KEY
    
    #if defined(SKIP_UART_CONFIRMATION) && !defined(USER_KEY)
    #error You have to define USER_KEY for boards that does not have UART
    #endif
    
    #ifdef USER_KEY
    /** @brief The user-defined HMAC key to use for personalization */
    #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
    /** @brief The data to store in key slot 0 */
    const uint8_t user_key_data[32] = {MY_HMAC_KEY};
    #endif
    
    #ifdef USER_SOFT_KEY
    /** @brief The user-defined soft HMAC key to use for EEPROM personalization */
    #define MY_SOFT_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
    /** @brief The data to store as soft HMAC key in EEPROM */
    const uint8_t user_soft_key_data[32] = {MY_SOFT_HMAC_KEY};
    #endif
    
    #ifdef USER_SOFT_SERIAL
    /** @brief The user-defined soft serial to use for EEPROM personalization */
    #define MY_SOFT_SERIAL 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
    /** @brief The data to store as soft serial in EEPROM */
    const uint8_t user_soft_serial[9] = {MY_SOFT_SERIAL};
    #endif
    
    #ifdef USER_AES_KEY
    /** @brief The user-defined AES key to use for EEPROM personalization */
    #define MY_AES_KEY 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
    /** @brief The data to store as AES key in EEPROM */
    const uint8_t user_aes_key[16] = {MY_AES_KEY};
    #endif
    
    

    in the second code i have to place the Keys which i got on first run.

    after this i can upload the normally gateway sketch

    is that correct?
    thank you very much


  • Hardware Contributor

    @meddie said in Encryption, Signing and OTA is there any how-to?:

    if i understood it correctly, i have to use the securitypersonalization.ino on the gw. For the first time i upload this code
    When its uploaded on first run i will get the AES and HMAC Key, which i have to notice and safe securely.

    Then i have to upload the sketch again with this code:
    in the second code i have to place the Keys which i got on first run.
    after this i can upload the normally gateway sketch

    is that correct?
    thank you very much

    As far as I understand it you can generate and safe the keys in one run (not 100% sure about that) on the gateway. Afterwards you install the normal gateway sketch.
    And you also have to use the personalizer sketch on every node to add the HMAC/AES keys.

    This is really a topic where we need an easier step-by-step tutorial imho. Perhaps once I find the time for it I'll experiment some more and write such a guide myself (will take some time though).



  • @meddie

    Hello, I have also begun to look at the hardware lock with ATSHA204.

    When you generate the key, you do so with SecurityPersonalizer.ino

    https://forum.mysensors.org/topic/6019/sensebender-gateway-and-atsha204

    //Mattias


  • Contest Winner

    If you feel this page is inadequate as the description for how to use signing, I am all ears for getting suggestions on how to improve it.



  • @Anticimex

    Personally, I think it is I who do not understand really. and then is afraid to start by destroying the hardware

    //Mattias


  • Hardware Contributor

    @Anticimex said in Encryption, Signing and OTA is there any how-to?:

    If you feel this page is inadequate as the description for how to use signing, I am all ears for getting suggestions on how to improve it.

    Its a great read but a little too much on the theoretical side for me. I think we should add some practical and complete example. Something like:

    • get the gw and use this xyz sketch to generate the keys
    • copy the keys
    • save the keys with this xyz sketch
    • flash the normal gateway sketch

    then take a node

    • burn the keys to it
    • add your xyz sketch with these parts to enable whitelisting, ....

    Something like that so that you can point any "noob" at this and tell him to do like that.


  • Contest Winner

    @LastSamurai well, if you read far enough you get exactly that. At least as how I view things, but as I am the designer, I might find things obvious which are not. But I really have tried to add specific use case examples and how to configure them.


  • Hardware Contributor

    @Anticimex Overall I like your text (and your work!) but I can only tell you what I found to be missing when I read this:
    the step by step tutorial (like a short summary of your text) containing versions of the personalizer sketch doing configured to do exactly whats needed in that step. Your examples only cover the the last part of my list (the node configuration)!


  • Contest Winner

    @LastSamurai I see. Well, I intentionally left the personalizer to be highly customizable since users have varying requirements, but I can add flags to it which preconfigure some typical usecases if that would help?


  • Contest Winner

    I hope to be able to file a pull request with updates to the personalizer this or next week. @LastSamurai @MLs @meddie i would really appreciate if you tested and reviewed the change so that you (and others) no longer are deterred from using signing due to its complexity. I will update the pull request until you feel confident in the procedure. I will post a link here when I have something to show for.


  • Hardware Contributor

    @Anticimex said in Encryption, Signing and OTA is there any how-to?:

    @LastSamurai I see. Well, I intentionally left the personalizer to be highly customizable since users have varying requirements, but I can add flags to it which preconfigure some typical usecases if that would help?

    That would actually be great! Some flags that automatically set up for:

    • create everything at the gw and save it
    • node: takes the provided HMAC (and aes) and saves it, generates new node id

    and perhaps some others would really help me (and others I hope). I gladly test your new changes, just keep me updated!

    PS We could also add a section to your text describing that you need well working radios (+ caps) because of the longer message sizes. Signing doesn't work for all nodes for me due to that and when I started working with it I thought this to be a problem with signing.


  • Contest Winner

    @LastSamurai node IDs is not a signing thing so the personalizer will not touch that.
    And regarding working radios, the "real" documentation feature a troubleshooting section where that topic is covered. Doxygen that is. Link is available through the readme on the library on github. I will see if I can incorporate that somehow on the main site. Unfortunately there is no automatic link between the generate docs which are the most recent, and the article on the main site.


  • Hardware Contributor

    I meant the serial number (forgot that name and it is like a node id, right?). The one thats needed for e.g. whitelisting.

    The documentation mentions somewhere that signing might cause errors if the radios aren't working at a 100%? Haven't seen that but that might be important to avoid people being "afraid" of using signing.


  • Contest Winner

    Both serial and node id is used for whitelisting.
    However, only serial is generated by the personalizer (and only for software signing, atsha204a has a fixed serial).
    This is the full documentation with troubleshooting section: https://ci.mysensors.org/job/Verifiers/job/MySensors/branch/development/Doxygen_HTML/group__MySigninggrp.html



  • @Anticimex

    Ofcourse

    //Mattias


  • Contest Winner

    While I am working on the personalizer simplifications, perhaps you could have a look at https://www.mysensors.org/about/signing#how-to-use-this where there are (and have been all along) an explicit list of flags to enable/disable for "master" and "slave" devices. I believe this is what you were looking for @LastSamurai ?


  • Hardware Contributor

    @Anticimex Oh, right that looks very helpful! Some shortcuts for these would be great anyways 🙂


  • Contest Winner

    @LastSamurai I agree, and I will rename a a few concepts as well.


  • Contest Winner

    I am inclined to stick to the concept as documented instead of having "node" and "gateway" concepts as we discussed. I will still simplify the procedure.
    The reason for this is that I believe it is simpler to have this procedure:

    • Configure personalizer to generate keys
    • Reconfigure personalizer to retain and store generated keys

    as opposed to

    • Configure personalizer for "gateway" (to generate and store keys)
    • Configure personalizer for "node" (to store retained keys)

    The reason I think the first and original design is simpler is because it allows you to execute the personalizer once with one setting to obtain keys, then reconfigure the personalizer once and execute the same personalizer on ALL devices. That minimizes the risk of having misalignment in the personalized security data between the nodes. What I will do is to provide two "top-level" definitions which takes care of every setting except the setting of the retained autogenerated keys and the use of ATSHA204A or software signing. The personalizer does output the auto generated keys in a very copy+paste friendly manner so it is not difficult to set these.
    The only thing which need to be different between nodes/gateways is the serial (if soft signing is used) so that will always be randomly generated (unless one specifically reconfigure the personalizer to use a specific serial).

    Thoughts on this? I am still open for input as it is you that are the users 🙂
    EDIT: I will have four "top-level" flags, so you select ATSHA or soft variant at the top level.


  • Hardware Contributor

    @Anticimex That sounds really nice to me. I would also (if thats possible without breaking something in the code) move these new flags and the settings for the HMAC (and everything else that needs to be inserted) to the top of the sketch, so that if you stay with the "default" settings you don't need to scroll down. Just for easy of use and for beginners.

    Great timing from you btw: I am in the process of switching the controller anyways and will redo some of my nodes too. Now I can incorporate signing (and perhaps encryption) too.


  • Contest Winner

    @LastSamurai I am pretty much rewriting the entire personalizer. So I am glad to have a motivated test team at hand 😉
    Ease of use is prio1 with flexibility coming in second.


  • Mod

    Agreed, if you can make the configuration easy of the most common commands, it would be great for beginners. 😉


  • Contest Winner

    There is a pull request now for a new personalizer. Please try it. It might still be a few issues, but I need more test coverage.
    https://github.com/mysensors/MySensors/pull/794


  • Hardware Contributor

    @Anticimex I already download the pr... the new sketch looks very nice! I'll try it out tomorrow.


  • Hardware Contributor

    Seems to work just fine. The output is way cleaner and the options are easy to use imo (tried the PERSONALIZE_SOFT_RANDOM_SERIAL). One questions though:
    The output gives me EEPROM and Key Storage. With different values for the Serial number. What's the difference here?


  • Contest Winner

    @LastSamurai Can you please provide the output?
    The sketch will output EEPROM value first, and (in the case of PERSONALIZE_SOFT_RANDOM_SERIAL) generate a new serial which will replace the value in EEPROM. If you run the sketch without any flags set, it will just show the currently stored states.


  • Hardware Contributor

    Haven't saved it. Will rerun it later 😉 There were just different categories and one was EEPROM another was Key Storage. Inbetween was the gererated key (which was the same as in the key storage). So I guess it read the values, wrote the new ones and displayed the new ones. Might be a little confusing though. I'll try to post it later

    Everything seems to be working now though with the signing enabled.


  • Contest Winner

    @LastSamurai EEPROM is exactly what it says; the data in EEPROM.
    Key storage is the keys being stored "somewhere", it could be EEPROM (if you use soft signing) or ATSHA204A if you use that. If you execute the key generation stage, you will see "Key generation" instead of "Key storage".
    The special case is the PERSONALIZE_SOFT_RANDOM_SERIAL in which you will do both key generation and key storage (but only generation for the serial).


  • Hardware Contributor

    This is what I get:

    +------------------------------------------------------------------------------------+
    |                           MySensors security personalizer                          |
    +------------------------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                               Configuration settings                               |
    +------------------------------------------------------------------------------------+
    | * Guided personalization/storage of keys in EEPROM                                 |
    | * Guided storage and generation of random serial in EEPROM                         |
    | * Software based personalization (no ATSHA204A usage whatsoever)                   |
    | * Will not require UART confirmation before locking ATSHA204A configuration        |
    | * Will store HMAC key to EEPROM                                                    |
    | * Will store AES key to EEPROM                                                     |
    | * Will generate soft serial using software                                         |
    | * Will store soft serial to EEPROM                                                 |
    +------------------------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                           Hardware security peripherals                            |
    +--------------+--------------+--------------+------------------------------+--------+
    | Device       | Status       | Revision     | Serial number                | Locked |
    +--------------+--------------+--------------+------------------------------+--------+
    | AVR          | DETECTED     | N/A          | N/A (generation required)    | N/A    |
    +--------------+--------------+--------------+------------------------------+--------+
    
    +------------------------------------------------------------------------------------+
    |                                       EEPROM                                       |
    +--------+--------+------------------------------------------------------------------+
    | Key ID | Status | Key                                                              |
    +--------+--------+------------------------------------------------------------------+
    | HMAC   | OK     | ... |
    | AES    | OK     | 00000000000000000000000000000000                                 |
    | SERIAL | OK     | 0E0103FA44D749F163                                               |
    +--------+--------+------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                                   Key generation                                   |
    +--------+--------+------------------------------------------------------------------+
    | Key ID | Status | Key                                                              |
    +--------+--------+------------------------------------------------------------------+
    | SERIAL | OK     | 0F5B932A87D43AD318                                               |
    +--------+--------+------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                                    Key storage                                     |
    +--------+--------+------------------------------------------------------------------+
    | Key ID | Status | Key                                                              |
    +--------+--------+------------------------------------------------------------------+
    | HMAC   | OK     | ... |
    | AES    | OK     | 00000000000000000000000000000000                                 |
    | SERIAL | OK     | 0F5B932A87D43AD318                                               |
    +--------+--------+------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                                  WHAT TO DO NEXT?                                  |
    +------------------------------------------------------------------------------------+
    | This device has now been personalized. Run this sketch with its current settings   |
    | on all the devices in your network that have security enabled.                     |
    +------------------------------------------------------------------------------------+
    
    +------------------------------------------------------------------------------------+
    |                                  Execution result                                  |
    +------------------------------------------------------------------------------------+
    | SUCCESS                                                                            |
    +------------------------------------------------------------------------------------+
    

    Ah ok. Still a little confusing in my opinion. Why show the key storage at all with Soft_serial? In this case the key always gets saved in the eeprom (right?). Just the "key generation" and one eeprom afterwards or one before and one after (with different names) would be clearer imo.
    Just some (hopefully constructive) critisism. I still like it way more than the old system!


  • Contest Winner

    @LastSamurai Well, I designed it like this intentionally because I want the "experience" to be uniform.
    You have selected a mode which generates a key and stores a key. So it will shows the key(s) it generates and also the key(s) it store. Key generation and key storage is normally two separate things.
    You can if you so like completely customize what keys you generate and store using the "advanced" config flags.
    The log is designed to show exactly what is happening.
    You could if you wanted to tell it to generate a serial but not store it. Or tell it to not generate a serial but store one you have configured yourself. Hence the tables are separated.


  • Hardware Contributor

    @Anticimex Well that makes sense too. I was just a little confused seeing 2 serial keys the first time. I figured it out though, so other will too 😉
    Nice work though, much easier to use than the old version!

    When I have the time I'll try it with some other nodes in the next days.


  • Contest Winner

    @LastSamurai thanks. Appreciate the feedback. I am going to test it on a samd device as well and if it looks OK, I'll have the core team review and approve it. Then I'll start looking at the simplified security option.


  • Hardware Contributor

    @Anticimex I just tested the "#define PERSONALIZE_SOFT" option with my new gateway to set serial number and HMAC key and everything seems to work just fine. I have no devices with hardware encryption (yet) so I can't test that one.


  • Contest Winner

    @LastSamurai hardware encryption? Well, from a personalization perspective, encryption is handled the same. AES key is always stored in eeprom so you can use encryption for nrf24 (as rfm69 is the only radio currently with a hw AES accelerator). Rfm69 still gets the key from eeprom though.


  • Hardware Contributor

    @Anticimex Badly formulated from me 😉 What I meant is signing (+ perhaps encryption too) using the ATSHA204A instead of the software backend. All tests I have done are with the software one.


  • Contest Winner

    @LastSamurai Ah, no, the ATSHA204A is only for signing. You can however go "advanced" and configure the personalizer to use the ATSHA204A to generate a random AES key for encryption use. But the ATSHA204A is not involved in encryption or decryption operations.


  • Contest Winner

    The updated personalizer has now been merged to the development branch (BETA channel).


  • Hardware Contributor

    Great! Any idea when it will be in the normal branch? Haven been using that for most of the time.


  • Contest Winner

    @LastSamurai no, there is no schedule set for the next release to my knowledge.


 

346
Online

7.6k
Users

8.5k
Topics

91.2k
Posts