diff --git a/libraries/MySensors/core/MySigning.h b/libraries/MySensors/core/MySigning.h index 9591295..b0c7fcc 100644 --- a/libraries/MySensors/core/MySigning.h +++ b/libraries/MySensors/core/MySigning.h @@ -35,8 +35,8 @@ * 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 + * this is known as authenticity. Bob needs some way of determining that the message is authentic from Alice, when Bob receives it. + * This prevents an eavesdropper, Eve, to trick Bob into thinking it was Alice that sent a message Eve in fact transmitted. Bob also needs * 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.
@@ -156,7 +156,11 @@ * This has to be set by at least one of the node in a "pair" or nobody will actually start calculating a signature for a message. * Just set the flag @ref MY_SIGNING_REQUEST_SIGNATURES and the node will inform the gateway that it expects the gateway to sign all * messages sent to the node. If this is set in a gateway, it will @b NOT force all nodes to sign messages to it. It will only require - * signatures from nodes that in turn require signatures. + * signatures from nodes that in turn require signatures.
+ * A node can have three "states" with respect to signing: + * 1. Node does not support signing in any way (neither @ref MY_SIGNING_ATSHA204 nor @ref MY_SIGNING_SOFT is set) + * 2. Node does support signing but don't require messages sent to it to be signed (@ref MY_SIGNING_REQUEST_SIGNATURES is not set) + * 3. Node does support signing and require messages sent to it to be signed (@ref MY_SIGNING_REQUEST_SIGNATURES is set) * * Secondly, you need to verify the configuration for the backend.
* For hardware backed signing it is the pin the device is connected to. In MyConfig.h there are defaults which you might need to adjust to @@ -180,7 +184,7 @@ * @code{.cpp} * #define MY_SIGNING_SOFT * #define MY_SIGNING_SOFT_SERIAL 0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56,0x78 - * #defune MY_SIGNING_SOFT_RANDOMSEED_PIN 7 + * #define MY_SIGNING_SOFT_RANDOMSEED_PIN 7 * #define MY_SIGNING_SOFT_HMAC_KEY 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f,0xa0,0xb0,0xc0,0xd0,0xe0,0xf0,0x11,0x22 * #define MY_SIGNING_REQUEST_SIGNATURES * #include @@ -267,7 +271,7 @@ * * 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.\n - * This node require signing since you do not want an unauthorized person sending it orders to open the door. + * This node requires 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 @@ -276,7 +280,7 @@ * * 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 now 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"? * @@ -290,7 +294,7 @@ * The whitelist is stored on the node that require signatures. When a received message is verified, the serial of the sender is looked up in a * list stored on the receiving node, and the corresponding serial stored in the list for that sender is then included in the signature verification * process. The list is stored as the value of the flag that enables whitelisting, @ref MY_SIGNING_NODE_WHITELISTING.
- * For whitelisting to work, the sending node also need to have whitelisting enabled.
+ * For whitelisting to work, the sending node also needs to have whitelisting enabled.
* * Whitelisting 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 @@ -317,7 +321,7 @@ * @code{.cpp} * #define MY_SIGNING_SOFT * #define MY_SIGNING_SOFT_SERIAL 0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56,0x78 - * #defune MY_SIGNING_SOFT_RANDOMSEED_PIN 7 + * #define MY_SIGNING_SOFT_RANDOMSEED_PIN 7 * #define MY_SIGNING_SOFT_HMAC_KEY 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f,0xa0,0xb0,0xc0,0xd0,0xe0,0xf0,0x11,0x22 * #define MY_SIGNING_REQUEST_SIGNATURES * #define MY_SIGNING_NODE_WHITELISTING {{.nodeId = GATEWAY_ADDRESS,.serial = {0x09,0x08,0x07,0x06,0x05,0x04,0x03,0x02,0x01}},{.nodeId = 2,.serial = {0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09}}} @@ -369,11 +373,11 @@ * * Due to the limiting factor of our cheapest 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 covered in the "Typical usecases" chapter below.
+ * this, and that is covered in the "Typical use cases" 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. * - * @section MySigningusecases Typical usecases + * @section MySigningusecases Typical use cases * * "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. @@ -383,23 +387,75 @@ * 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. + * to replace at least the signing circuit in case you need to revoke the PSK because some other node in your network gets compromised.
+ * You need to make your node require signed messages but you do not necessarily need to make your gateway require signed messsages (unless you + * are concerned that someone might spoof the lock status of your lock).
+ * Configuration example for the secure lock node:
+ * @code{.cpp} + * #define MY_SIGNING_ATSHA204 + * #define MY_SIGNING_REQUEST_SIGNATURES + * #include + * ... + * @endcode + * If you do also want your gateway to require signatures from your lock you just enable the same (or similar if using software signing) settings + * in the gateway. * * @subsection MySigningpatio 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 + * 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. + * This is an unlikely use case because there really is no reason to sign sensor values. If you for some reason want to obfuscate sensor data, + * encryption is a better alternative.
+ * Configuration example for a motion sensor with whitelisting (it has to have the gateway whitelisted since the gateway will send signed messages to the node):
+ * @code{.cpp} + * #define MY_SIGNING_SOFT + * #define MY_SIGNING_SOFT_SERIAL 0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56,0x78 + * #define MY_SIGNING_SOFT_RANDOMSEED_PIN 7 + * #define MY_SIGNING_SOFT_HMAC_KEY 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f,0xa0,0xb0,0xc0,0xd0,0xe0,0xf0,0x11,0x22 + * #define MY_SIGNING_REQUEST_SIGNATURES + * #define MY_SIGNING_NODE_WHITELISTING {{.nodeId = GATEWAY_ADDRESS,.serial = {0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88}}} + * #include + * ... + * @endcode * + * The gateway needs to configured with a whitelist (and it have to have an entry for all nodes that send and/or require signed messages):
+ * @code{.cpp} + * #define MY_SIGNING_SOFT + * #define MY_SIGNING_SOFT_SERIAL 0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88 + * #define MY_SIGNING_SOFT_RANDOMSEED_PIN 7 + * #define MY_SIGNING_SOFT_HMAC_KEY 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f,0xa0,0xb0,0xc0,0xd0,0xe0,0xf0,0x11,0x22 + * #define MY_SIGNING_REQUEST_SIGNATURES + * #define MY_SIGNING_NODE_WHITELISTING {{.nodeId = MOTION_SENSOR_ID,.serial = {0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56,0x78}}} + * #include + * ... + * @endcode + * @subsection MySigningkeyfob 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. + * thus rendering the keyfob useless without having to replace your nodes. You can also use whitelisting to revoke your lost keyfob.
+ * Configuration example for the keyfob (keyfob will only transmit to another node and not receive anything):
+ * @code{.cpp} + * #define MY_SIGNING_ATSHA204 + * #define MY_SIGNING_NODE_WHITELISTING {} + * #include + * ... + * @endcode + * Configuration example for the door controller node (should require signing from anyone who wants to control it):
+ * @code{.cpp} + * #define MY_SIGNING_SOFT + * #define MY_SIGNING_SOFT_SERIAL 0x12,0x34,0x56,0x78,0x90,0x12,0x34,0x56,0x78 + * #define MY_SIGNING_SOFT_RANDOMSEED_PIN 7 + * #define MY_SIGNING_SOFT_HMAC_KEY 0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x10,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0x0a,0x0b,0x0c,0x0d,0x0e,0x0f,0xa0,0xb0,0xc0,0xd0,0xe0,0xf0,0x11,0x22 + * #define MY_SIGNING_REQUEST_SIGNATURES + * #define MY_SIGNING_NODE_WHITELISTING {{.nodeId = GATEWAY_ADDRESS,.serial = {0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88}},{.nodeId = KEYFOB_ID,.serial = {}}} + * #include + * ... + * @endcode * * @subsection MySigningsketches Relevant sketches *