Fixes the Markdown lint config and affected files

I also ran our documentation against a few other linters, to see what they would find, and fixed accordingly.
kaczmarczyck · Jan 12, 2024 · 9ea04da · 9ea04da
1 parent 298db9e
commit 9ea04da
Show file tree

Hide file tree

Showing 6 changed files with 105 additions and 117 deletions.
diff --git a/.github/workflows/mdlint.yml b/.github/workflows/mdlint.yml
@@ -17,5 +17,5 @@ jobs:
         uses: nosborn/github-action-markdown-cli@v3
         with:
           files: '**/*.md'
-          ignore_files: "third_party/*"
-          config_file: ".markdownlint.json"
+          config_file: '.markdownlint.json'
+          ignore_files: 'third_party/*'
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -1,35 +1,23 @@
 {
     "default": true,
-    "heading-style": {
+    "MD003": {
         "style": "atx"
     },
-    "no-trailing-spaces": {
+    "MD007": {
+        "indent": 4
+    },
+    "MD009": {
         "br_spaces": 0,
         "strict": true
     },
-    "ul-indent": {
-        "indent": 4
-    },
-    "line-length": {
+    "MD013": {
         "line_length": 80,
         "code_blocks": false
     },
-    "list-marker-space": {
-        "ol_single": 2,
-        "ol_multi": 2,
-        "ul_single": 3,
-        "ul_multi": 3
-    },
-    "no-inline-html": {
+    "MD033": {
         "allowed_elements": [
-            "img"
-        ]
-    },
-    "fenced-code-language": true,
-    "code-block-style": {
-        "style": "fenced"
-    },
-    "code-fence-style": {
-        "style": "backtick"
+        "img"
+	]
     }
-}
+}
+
diff --git a/bootloader/README.md b/bootloader/README.md
@@ -2,8 +2,8 @@
 
 This bootloader supports upgradability for OpenSK. Its functionality is to
 
--   check images on A/B partitions,
--   boot the most recent valid partition.
+- check images on A/B partitions,
+- boot the most recent valid partition.
 
 ## How to use
 

diff --git a/docs/customization.md b/docs/customization.md
@@ -7,18 +7,18 @@
 All the generated certificates and private keys are stored in the directory
 `crypto_data/`. The expected content after running our `setup.sh` script is:
 
-File                     | Purpose
------------------------- | --------------------------------------------------------
-`aaguid.txt`             | Text file containaing the AAGUID value
-`opensk_ca.csr`          | Certificate sign request for the Root CA
-`opensk_ca.key`          | ECC secp256r1 private key used for the Root CA
-`opensk_ca.pem`          | PEM encoded certificate of the Root CA
-`opensk_ca.srl`          | File generated by OpenSSL
-`opensk_cert.csr`        | Certificate sign request for the attestation certificate
-`opensk_cert.pem`        | PEM encoded certificate used for the authenticator
-`opensk.key`             | ECC secp256r1 private key used for the autenticator
-`opensk_upgrade.key`     | Private key for signing upgrades through CTAP
-`opensk_upgrade_pub.pem` | Public key added to the firmware for verifying upgrades
+| File                     | Purpose                                         |
+| ------------------------ | ----------------------------------------------- |
+| `aaguid.txt`             | Text file containaing the AAGUID value          |
+| `opensk_ca.csr`          | Certificate sign request for the Root CA        |
+| `opensk_ca.key`          | ECC secp256r1 private key used for the Root CA  |
+| `opensk_ca.pem`          | PEM encoded certificate of the Root CA          |
+| `opensk_ca.srl`          | File generated by OpenSSL                       |
+| `opensk_cert.csr`        | CSR for attestation certificate                 |
+| `opensk_cert.pem`        | PEM encoded certificate for the authenticator   |
+| `opensk.key`             | ECC secp256r1 private key for the autenticator  |
+| `opensk_upgrade.key`     | Private key for signing upgrades through CTAP   |
+| `opensk_upgrade_pub.pem` | Public key for verifying upgrades               |
 
 If you want to use your own attestation certificate and private key,
 replace the `opensk_cert.pem` and `opensk.key` files. The script at
@@ -50,20 +50,20 @@ carefully if you want to take this privacy risk.
 If you build your own security key, depending on the hardware you use, there are
 a few things you can personalize:
 
-1.  If you have multiple buttons, choose the buttons responsible for user
-    presence in `src/main.rs`.
-1.  If you have colored LEDs, like different blinking patterns and want to play
-    around with the code in `src/main.rs` more, take a look at e.g. `wink_leds`.
-1.  You find more options and documentation in `src/ctap/customization.rs`,
-    including:
-    *   The default level for the credProtect extension.
-    *   The default minimum PIN length, and what relying parties can set it.
-    *   Whether you want to enforce alwaysUv.
-    *   Settings for enterprise attestation.
-    *   The maximum PIN retries.
-    *   Whether you want to use batch attestation.
-    *   Whether you want to use signature counters.
-    *   Various constants to adapt to different hardware.
+1. If you have multiple buttons, choose the buttons responsible for user
+   presence in `src/main.rs`.
+1. If you have colored LEDs, like different blinking patterns and want to play
+   around with the code in `src/main.rs` more, take a look at e.g. `wink_leds`.
+1. You find more options and documentation in `src/ctap/customization.rs`,
+   including:
+   * The default level for the credProtect extension.
+   * The default minimum PIN length, and what relying parties can set it.
+   * Whether you want to enforce alwaysUv.
+   * Settings for enterprise attestation.
+   * The maximum PIN retries.
+   * Whether you want to use batch attestation.
+   * Whether you want to use signature counters.
+   * Various constants to adapt to different hardware.
 
 ### Testing and Fuzzing
 

diff --git a/docs/debugging.md b/docs/debugging.md
@@ -59,15 +59,15 @@ JLinkRTTClient
 You can enhance the debug output by adding flags to the deploy command (see
 below for details):
 
-*   `--debug`: more debug messages
-*   `--panic-console`: add panic messages
-*   `--debug-allocations`: print information about the used heap
+* `--debug`: more debug messages
+* `--panic-console`: add panic messages
+* `--debug-allocations`: print information about the used heap
 
 Adding debugging to your firmware increases resource usage, including
 
-*   USB communication speed
-*   RAM usage
-*   binary size
+* USB communication speed
+* RAM usage
+* binary size
 
 Depending on your choice of board, you may have to increase the available stack
 for kernel or app, or disable features so that the binary fits the flash. Also

diff --git a/docs/install.md b/docs/install.md
@@ -8,27 +8,27 @@ This document lists required steps to start build your own OpenSK.
 
 OpenSK supports different ways to flash your board:
 
-*   [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/)
-    (default method).
-*   [OpenOCD](http://openocd.org/).
-*   [pyOCD](https://pypi.org/project/pyocd/).
-*   [nrfutil](https://pypi.org/project/nrfutil/) for the USB dongle boards that
-    support it, which allows you to directly flash a working board over USB
-    without additional hardware.
+* [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/)
+  (default method).
+* [OpenOCD](http://openocd.org/).
+* [pyOCD](https://pypi.org/project/pyocd/).
+* [nrfutil](https://pypi.org/project/nrfutil/) for the USB dongle boards that
+  support it, which allows you to directly flash a working board over USB
+  without additional hardware.
 
 ### Software requirements
 
 In order to compile and flash a working OpenSK firmware, you will need the
 following:
 
-*   rustup (can be installed with [Rustup](https://rustup.rs/))
-*   python3 and pip (can be installed with the `python3-pip` package on Debian)
-*   the OpenSSL command line tool (can be installed and configured with the
-    `libssl-dev` and `pkg-config` packages on Debian)
-*   `nrfutil` (pip package of the same name), if you want to flash
-    a device with DFU. Read the disclaimer below.
-*   `uuid-runtime` if you are missing the `uuidgen` command.
-*   `llvm` and `gcc-arm-none-eabi` if you want to use the upgradability feature.
+* rustup (can be installed with [Rustup](https://rustup.rs/))
+* python3 and pip (can be installed with the `python3-pip` package on Debian)
+* the OpenSSL command line tool (can be installed and configured with the
+  `libssl-dev` and `pkg-config` packages on Debian)
+* `nrfutil` (pip package of the same name), if you want to flash
+  a device with DFU. Read the disclaimer below.
+* `uuid-runtime` if you are missing the `uuidgen` command.
+* `llvm` and `gcc-arm-none-eabi` if you want to use the upgradability feature.
 
 The proprietary software to use the default programmer can be found on the
 [Segger website](https://www.segger.com/downloads/jlink). Please follow their
@@ -54,31 +54,31 @@ If this is your first time installing OpenSK, please skip directly to
 Depending on the difference to your last state, you may need some of the
 following steps:
 
-*   If you are not just testing minor changes, reset and redo the setup. This
-    will delete all uncommited changes.
+* If you are not just testing minor changes, reset and redo the setup. This
+  will delete all uncommited changes.
 
-    ```shell
-    ./reset.sh
-    ./setup.sh
-    ```
+  ```shell
+  ./reset.sh
+  ./setup.sh
+  ```
 
-*   Flash your board according to the
-    [flashing instructions below](#Flashing-a-firmware]. If you come from an
-    OpenSK version before the 2.0 certified one, your credential storage is not
-    backwards compatible and you have to reset it. :warning: You will lose
-    logins to all websites that you registered with OpenSK. To erase your
-    persistent storage, run the deploy script twice: Once with the application
-    parameter `--erase_storage`, and once with `--opensk` as usual.
+* Flash your board according to the [instructions below](#flashing-a-firmware).
 
-    This reset also clears the certificate. For a privacy discussion, see the
-    [certificate section in Customization](customization.md#Certificate-considerations).
-    If you want to reinstall it, you also need to rerun:
+If you come from an OpenSK version before the 2.0 certified one, your credential
+storage is not backwards compatible and you have to reset it. :warning: You will
+lose logins to all websites that you registered with OpenSK. To erase your
+persistent storage, run the deploy script twice: Once with the application
+parameter `--erase_storage`, and once with `--opensk` as usual.
 
-    ```shell
-    ./tools/configure.py \
-        --certificate=crypto_data/opensk_cert.pem \
-        --private-key=crypto_data/opensk.key
-    ```
+This reset also clears the certificate. For a privacy discussion, see the
+[certificate section in Customization](customization.md#Certificate-considerations).
+If you want to reinstall it, you also need to rerun:
+
+```shell
+./tools/configure.py \
+    --certificate=crypto_data/opensk_cert.pem \
+    --private-key=crypto_data/opensk.key
+```
 
 #### Initial setup
 
@@ -93,17 +93,17 @@ cd OpenSK
 
 The setup script performs the following steps:
 
-1.  Make sure that the git submodules are checked out.
+1. Make sure that the git submodules are checked out.
 
-1.  Apply our patches that haven't yet been merged upstream to both
-    [Tock](https://github.com/tock/tock) and
-    [libtock-rs](https://github.com/tock/libtock-rs).
+1. Apply our patches that haven't yet been merged upstream to both
+   [Tock](https://github.com/tock/tock) and
+   [libtock-rs](https://github.com/tock/libtock-rs).
 
-1.  Generate crypto material, see [Customization](customization.md) for details.
+1. Generate crypto material, see [Customization](customization.md) for details.
 
-1.  Install the correct Rust toolchain for ARM devices.
+1. Install the correct Rust toolchain for ARM devices.
 
-1.  Install [tockloader](https://github.com/tock/tockloader).
+1. Install [tockloader](https://github.com/tock/tockloader).
 
 Additionally on Linux, you need to install a `udev` rule file to allow non-root
 users to interact with OpenSK devices. To install it, execute:
@@ -132,24 +132,24 @@ for understand privacy tradeoffs.
 
 From here on, please follow the instructions for your hardware:
 
-*   [Nordic nRF52840-DK](boards/nrf52840dk.md)
-*   [Nordic nRF52840 Dongle](boards/nrf52840_dongle.md)
-*   [Makerdiary nRF52840-MDK USB dongle](boards/nrf52840_mdk.md)
-*   [Feitian OpenSK dongle](boards/nrf52840_feitian.md)
+* [Nordic nRF52840-DK](boards/nrf52840dk.md)
+* [Nordic nRF52840 Dongle](boards/nrf52840_dongle.md)
+* [Makerdiary nRF52840-MDK USB dongle](boards/nrf52840_mdk.md)
+* [Feitian OpenSK dongle](boards/nrf52840_feitian.md)
 
 ### Advanced installation
 
 We recommend that you flash your development board with JTAG and dongles with
 DFU, as described in the [board documentation](#flashing-a-firmware) linked
 above. However, we support other programmers:
 
-*   OpenOCD: `./deploy.py --board=nrf52840_dongle_opensk --opensk
-    --programmer=openocd`
-*   pyOCD: `./deploy.py --board=nrf52840_dongle_opensk --opensk
-    --programmer=pyocd`
-*   Custom: `./deploy.py --board=nrf52840_dongle_opensk --opensk
-    --programmer=none`. In this case, an IntelHex file will be created and how
-    to program a board is left to the user.
+* OpenOCD: `./deploy.py --board=nrf52840_dongle_opensk --opensk
+  --programmer=openocd`
+* pyOCD: `./deploy.py --board=nrf52840_dongle_opensk --opensk
+  --programmer=pyocd`
+* Custom: `./deploy.py --board=nrf52840_dongle_opensk --opensk
+  --programmer=none`. In this case, an IntelHex file will be created and how
+  to program a board is left to the user.
 
 If your board is already flashed with Tock OS, you may skip installing it:
 `./deploy.py --board=nrf52840dk_opensk --opensk --no-tockos`
@@ -163,10 +163,10 @@ We experiment with a new CTAP command to allow upgrading your device without
 access to its debugging port. For that purpose, the flash storage is split into
 4 parts:
 
-*   the bootloader to decide with partition to boot
-*   firmware partition A
-*   firmware partition B
-*   the persistent storage for credentials
+* the bootloader to decide with partition to boot
+* firmware partition A
+* firmware partition B
+* the persistent storage for credentials
 
 The storage is backward compatible to non-upgradable boards. Deploying an
 upgradable board automatically installs the bootloader. Please keep in mind that