wiki/howto/Registry-Authentication.md

How Authentication Works

auth attributes within registry mntner objects define a public key that is used to verify the identity of the maintainer and prove that changes to registry objects are authorised.

When a pull request is submitted to the registry, the submitter signs the git commit hash with their private key. The registry maintainers will then check the signature against the registered public key to authorise the change.

The signature and verification process varies depending on the type of public key within the auth attribute.

---

The registry now contains an experimental script 'sign-my-commit' which can authenticate requests using PGP or generic SSH key signing. Users are encouraged to use the script where possible as it will help with automating pull request reviews.

Run ./sign-my-commit --help to get usage information.

If the script fails, please report the problem using the registry issue log (or better fix it and submit a PR!). You can always sign your commit manually using the methods below.

---

Finding the commit hash

git log will list all the recent commits and show the commit hash:

commit 6e2e9ac540e2e4e3c3a135ad90c8575bb8fa1784 (HEAD -> master)
Author: foo <foo@baz.com>
Date:   Mon Jan 01 01:01:01 2020 +0000

    Change some stuff

Authentication with PGP Key

PGP keys may be uploaded to a public keyserver for verification, or added in the registry.

Using a public keyserver

• Use the following auth attribute in your mntner object:

auth:               pgp-fingerprint <fingerprint>

Where <fingerprint> is your full 40-digit key fingerprint, without spaces.

• Ensure that your public key has been uploaded to a public keyserver, e.g. SKS, OpenPGP, keybase.

Adding to the registry

• Use the following auth attribute in your mntner object:

auth:               PGPKEY-<fprint>

Where <fprint> is the last 8 digits from your key fingerprint.

• Create a key-cert object for your public key, using PGPKEY-<fprint> for the filename. Do browse the registry and check the existing objects for examples.

Signing your commits

• Use git commit -S to commit and sign your change. See the github guide.

• If you have already committed your change, you can sign it using.

git commit --amend --no-edit -S

Verifying the signature

• Use git log --show-signature to show recent commits and signatures.

Authentication using an SSH key

The generic format for authentication using an SSH key is as follows:

auth:               ssh-<keytype> <pubkey>

There are examples below for each specific key type.

Generic process for signing with an SSH key

OpenSSH v8 introduced new functionality for creating signatures using SSH keys. If you have an older version, you can compile the latest version of ssh-keygen from the openssh-portable repo.

Use the following to sign the latest <commit hash> (that you found using git log)

echo "<commit hash>" | ssh-keygen -Y sign -f <private key file> -n dn42

Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it. It can help to also include the commit hash that you have signed, to avoid any confusion.

Verifying the signature

The following procedure will verify the signature (using the <commit hash>, your <pubkey> and the <signature> generated in the previous step.

Create a temporary file containing the signature

echo "<signature>" > sig.tmp

Create a temporary 'allowed users' file

echo "YOU-MNT ssh-<keytype> <pubkey>" > allowed.tmp

Verify the signature

echo "<commit hash>" | \
    ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp

Authentication with an SSH RSA key

• Use the following auth attribute in your mntner object:

auth:               ssh-rsa <pubkey>

Where <pubkey> is the ssh public key copied from your id_rsa.pub file.

Signing your commits

If you cannot use the generic SSH process described above then RSA signatures can also be created using openssl.

Use the following to sign your <commit hash> (that you found using git log)

openssl pkeyutl \
   -sign \
   -inkey ~/.ssh/id_rsa \
   -in <(echo "<commit hash>") | base64

Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it. It can help to also include the commit hash that you have signed, to avoid any confusion.

Verifying the signature

The following script will verify the signature (using the <commit hash>, your rsa <pubkey> and the <signature> generated in the previous step.

openssl pkeyutl \
   -verify \
   -pubin \
   -in <(echo "<commit hash>") \
   -inkey <(ssh-keygen \
               -e \
               -m PKCS8 \
               -f <(echo "ssh-rsa <pubkey>")\
            ) \
   -sigfile <(echo "<signature>" | base64 -d)

Authentication with an SSH ed25519 key

• Use the following auth attribute in your mntner object:

auth:               ssh-ed25519 <pubkey>

Where <pubkey> is the ssh public key copied from your id_ed25519.pub file.

Signing your commits

There is no alternative process for signing using ed25519 keys, you must use the generic process described above. The process only works with ssh-keygen versions >= v8.

Use the following to sign your <commit hash> (that you found using git log)

echo "<commit hash>" | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n dn42

Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it. It can help to also include the commit hash that you have signed, to avoid any confusion.

Verifying the signature

The following procedure will verify the signature (using the <commit hash>, your ed25519 <pubkey> and the <signature> generated in the previous step.

Create a temporary file containing the signature

echo "<signature>" > sig.tmp

Create a temporary 'allowed users' file

echo "YOU-MNT ssh-ed25519 <pubkey>" > allowed.tmp

Verify the signature

echo "<commit hash>" | \
    ssh-keygen -Y verify -f allowed.tmp -n dn42 -I YOU-MNT -s sig.tmp

Authentication with an SSH ecdsa key

• Use the following auth attribute in your mntner object:

auth:               ecdsa-sha2-nistp256 <pubkey>

Where <pubkey> is the ssh public key copied from your id_ecdsa.pub file.

Signing your commits

If you cannot use the generic SSH process described above then ecdsa signatures can also be created using openssl.

DO NOT do this on your original ssh key.
Make a copy and use the copy as the ssh-keygen command below will overwrite the key file given.

Convert your private ssh key to a file that openssl can read:
DO THIS ON A COPY OF YOUR SSH KEY

ssh-keygen -p -m pem -f <private key file copy>

Sign the commit hash using your ecdsa key, using openssl:

openssl pkeyutl -sign \
    -inkey <converted key file> \
    -in <(echo "<commit hash>") | base64

Post the signature in to the 'Conversation' section of your pull request to allow the registry maintainers to verify it. It can help to also include the commit hash that you have signed, to avoid any confusion.

Verifying the signature

The following script will verify the signature (using the <commit hash>, your ecdsa <pubkey> and the <signature> generated in the previous step.

openssl pkeyutl \
   -verify \
   -pubin \
   -in <(echo "<commit hash>") \
   -inkey <(ssh-keygen \
               -e \
               -m PKCS8 \
               -f <(echo "ecdsa-sha2-nistp256 <pubkey>")\
            ) \
   -sigfile <(echo "<signature>" | base64 -d)