explain site.conf signature pubkeys in docs

[ruzko]

Bug report

What is the problem?

Using the autoupdater feature of Gluon requires specifying pubkeys at build time, but the docs don't explain what kind of pubkeys we're talking about.

This is the stanza in question, in https://gluon.readthedocs.io/en/latest/user/site.html:

autoupdater = {
    -- Default branch (optional), can be overridden by setting GLUON_AUTOUPDATER_BRANCH when building.
    -- Set GLUON_AUTOUPDATER_ENABLED to enable the autoupdater by default for newly installed nodes.
    branch = 'stable',

    -- List of branches. You may define multiple branches.
    branches = {
      stable = {
        name = 'stable',

        -- List of mirrors to fetch images from. IPv6 required!
        mirrors = {'http://1.updates.services.ffhl/stable/sysupgrade'},

        -- Number of good signatures required.
        -- Have multiple maintainers sign your build and only
        -- accept it when a sufficient number of them have
        -- signed it.
        good_signatures = 2,

        -- List of public keys of maintainers.
        pubkeys = {
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
        },
      },
    },

Perusing "site configurations in the wild" give me an inkling that we might be talking about gpg keys, and specifically the fingerprint of the gpg key. I'm not sure at all though, and would like clarification :)
Building gluon using SSH public keys fails for me, at least.

What is the expected behaviour?

Docs explain clearly what kind of public keys are expected, and links to a guide for how to get/produce it

[herbetom]

Yes, that should be better documented.

I hope the following helps you until that is done.

If you feel like it, you are also very welcome to submit a PR for improving the documents yourself. 🙈

---

Those are ECDSA keys:

https://github.com/freifunk-gluon/ecdsautils

ecdsautils is probably packaged for your distro (from the top of my head at least Debian, AUR, nixpkgs).
It's also available in the gluon build container.

You can generate your personal secret as following:

ecdsautil generate-key > yourSecret

You'll have to keep that file save.

The pubkey to put into the site is generated by providing your secret as the input:

ecdsautil show-key < yourSecret

For signing Gluon provides a helper script: contrib/sign.sh

It's given the location of the secret, as well as the location of the manifest as arguments and automatically appends the signature to the manifest file:

./contrib/sign.sh yourSecret output/images/sysupgrade/stable.manifest

(Your secret and the pubkey will have 64 characters. A signature has 128 characters. So, after you've shared your pubkey, you only want to share 128 character long strings going forward. If it's only 64 characters, you might have messed up somewhere and are in the process of sharing your secret :D)