Merge branch 'pr/30'

website/docs/developers/device/encryption.md

@@ -1,16 +1,15 @@
 ---
-id: crypto
+id: encryption
-title: Encryption in Meshtastic
+title: Meshtastic encryption
-sidebar_label: Crypto
+sidebar_label: Encryption
 ---
 
-Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However,
+Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts. Therefore we ask two things:
-the project developers are not cryptography experts. Therefore we ask two things:
 
-- If you are a cryptography expert, please review these notes and our questions below. Can you help us by reviewing our
+- If you are a cryptography expert, please review these notes and our questions below. Can you help us by reviewing our notes below and offering advice? We will happily give as much or as little credit as you wish ;-).
-  notes below and offering advice? We will happily give as much or as little credit as you wish ;-).
+- Consider our existing solution 'alpha' and probably fairly secure against a not particularly aggressive adversary (but we can't yet make a more confident statement).
-- Consider our existing solution 'alpha' and probably fairly secure against a not particularly aggressive adversary
+
-  (but we can't yet make a more confident statement).
+Always keep in mind [xkcd's note on encryption](https://xkcd.com/538/).
 
 ## Summary of strengths/weaknesses of our current implementation
 
@@ -32,7 +31,7 @@ Possible future areas of work (if there is enough interest - post in our [forum]
 If you are reviewing our implementation, this is a brief statement of our method.
 
 - We do all crypto at the SubPacket (payload) level only, so that all meshtastic nodes will route for others - even those channels which are encrypted with a different key.
-- Mostly based on reading [Wikipedia](<https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)>) and using the modes the ESP32 provides support for in hardware.
+- Mostly based on reading [Wikipedia](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)) and using the modes the ESP32 provides support for in hardware.
 - We use AES256-CTR as a stream cypher (with zero padding on the last BLOCK) because it is well supported with hardware acceleration.
 - Our AES key is 128 or 256 bits, shared as part of the 'Channel' specification.
 - The node number concatenated with the packet number is used as the NONCE. This nonce will be stored in flash in the device and should essentially never repeat. If the user makes a new 'Channel' (i.e. picking a new random 256 bit key), the packet number will start at zero.
@@ -52,4 +51,4 @@ I'm assuming that meshtastic is being used to hike in places where someone capab
 - I think the bigger encryption question is "what does the encryption need to do"? As it stands, an attacker who has yet to capture any of the devices cannot reasonably capture text or location data. An attacker who captures any device in the channel/mesh can read everything going to that device, everything stored on that device, and any other communication within the channel that they captured in encrypted form. If that capability basically matches your expectations, it is suitable for whatever adventures this was intended for, then, based on information publicly available or widely disclosed, the encryption is good. If those properties are distressing (like, device history is deliberately limited and you don't want a device captured today to endanger the information sent over the channel yesterday) we could talk about ways to achieve that (most likely synchronizing time and replacing the key with its own SHA256 every X hours, and ensuring the old key is not retained unnecessarily).
 - Two other things to keep in mind are that AES-CTR does not itself provide authenticity (e.g. an attacker can flip bits in replaying data and scramble the resulting plaintext), and that the current scheme gives some hints about transmission in the size. So, if you worry about an adversary deliberately messing-up messages or knowing the length of a text message, it looks like those might be possible.
 
-I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago.
+I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago.

website/docs/developers/device/port-numbers.md

@@ -0,0 +1,23 @@
+---
+id: portnum
+title: Meshtastic port numbers
+sidebar_label: Port numbers
+---
+
+For any new apps that run on the device or via sister apps on phones/PCs they should pick and use a unique 'portnum' for their application.
+
+If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to this master table.  PortNums should be assigned in the following range:
+
+| Portnum | Usage |
+| --- | --- |
+| 0-63 | Core Meshtastic use, do not use for third party apps |
+| 64-127 | Registered 3rd party apps, send in a pull request that adds a new entry to portnums.proto to  register your application |
+| 256-511 | Use one of these portnums for your private applications that you do not want to register publically |
+
+All other values are reserved.
+
+Note: This was formerly a Type enum named `typ` with the same id #
+
+We have changed to this 'portnum' based scheme for specifying app handlers for particular payloads. This change is backwards compatible by treating the legacy OPAQUE/CLEAR_TEXT values identically.
+
+The current list of port numbers can be found listed in the [protobufs](/docs/developers/protobufs/api#portnumsproto)

website/docs/legal/overview.md

@@ -9,7 +9,7 @@ slug: /legal
 This project is still pretty young but moving at a pretty good pace. Not all features are fully implemented in the current alpha builds.
 
 * We don't make these devices and they haven't been tested by UL or the FCC. If you use them you are experimenting and we can't promise they won't burn your house down ;-)
-* The encryption implementation is good but see this list of [caveats](/software/other/crypto.md#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
+* The encryption implementation is good but see this list of [caveats](/docs/developers/device/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
 
 ## Legal FAQ
 

website/docs/software/device/critical-faults.md

@@ -0,0 +1,23 @@
+---
+id: critical-error-codes
+title: Critical error codes
+sidebar_label: Critical error codes
+---
+
+The device might report these fault codes on the screen, but it will also be outputted on the device serial output. If you encounter a fault code, please post on the forum and we'll try to help.
+
+:::note
+This table is derived from the [protobufs](/docs/developers/protobufs/api#criticalerrorcode)
+:::
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| TxWatchdog | 1 | A software bug was detected while trying to send lora |
+| SleepEnterWait | 2 | A software bug was detected on entry to sleep |
+| NoRadio | 3 | No Lora radio hardware could be found |
+| Unspecified | 4 | Not normally used |
+| UBloxInitFailed | 5 | We failed while configuring a UBlox GPS |
+| NoAXP192 | 6 | This board was expected to have a power management chip and it is missing or broken |
+| InvalidRadioSetting | 7 | The channel tried to set a radio setting which is not supported by this chipset, radio comms settings are now undefined. |
+| TransmitFailed | 8 | Radio transmit hardware failure. We sent data to the radio chip, but it did not reply with an interrupt. |
+| Brownout | 9 | We detected that the main CPU voltage dropped below the minumum acceptable value |

website/docs/software/other/mesh-alg.md

@@ -26,7 +26,7 @@ After the preamble the 16 byte packet header is transmitted. This header is desc
 - id (4 bytes): the unique (wrt the sending node only) packet ID number for this packet. We use a large (32 bit) packet ID to ensure there is enough unique state to protect any encrypted payload from attack.
 - flags (4 bytes): Only a few bits are are currently used - 3 bits for for the "HopLimit" (see below) and 1 bit for "WantAck"
 
-After the packet header the actual packet is placed onto the the wire. These bytes are merely the encrypted packed protobuf encoding of the SubPacket protobuf. A full description of our encryption is available in [crypto](crypto.md). It is worth noting that only this SubPacket is encrypted, headers are not. Which leaves open the option of eventually allowing nodes to route packets without knowing the keys used to encrypt.
+After the packet header the actual packet is placed onto the the wire. These bytes are merely the encrypted packed protobuf encoding of the SubPacket protobuf. A full description of our encryption is available in [crypto](/docs/developers/device/encryption). It is worth noting that only this SubPacket is encrypted, headers are not. Which leaves open the option of eventually allowing nodes to route packets without knowing the keys used to encrypt.
 
 NodeIds are constructed from the bottom four bytes of the macaddr of the bluetooth address. Because the OUI is assigned by the IEEE and we currently only support a few CPU manufacturers, the upper byte is defacto guaranteed unique for each vendor. The bottom 3 bytes are guaranteed unique by that vendor.
 

website/sidebars.js

@@ -17,6 +17,11 @@ module.exports = {
     ],
     Software: [
       "software/overview",
+      {
+        "Meshtastic Device": [
+          "software/device/critical-error-codes",
+        ],
+      },
       {
         "Meshtastic Android": [
           "software/android/android-installation",
@@ -86,7 +91,6 @@ module.exports = {
           "software/other/install-OSX",
           "software/other/esp32-arduino-build-notes",
           "software/other/device-api",
-          "software/other/crypto",
           "software/other/build-instructions",
           "software/other/ant",
         ],
@@ -114,6 +118,8 @@ module.exports = {
       {
         Device: [
           "developers/device/radio-settings",
+          "developers/device/encryption",
+          "developers/device/portnum",
           "developers/device/supported-hardware",
           "developers/device/http-api",
           "developers/device/documents",