Exercise 9: Digital Signatures With Minisign

Minisign is a simple and convenient command line tool for signing files using Ed25519 and verifying their signatures. This exercise gives a basic introduction to Minisign and demonstrates how you can use it to sign files (e.g., your Coursework 2 submission) and verify the authenticity of files.

Installing Minisign on Your PC

If you have a Mac, you can install using Homebrew. On Windows, you can install with the Scoop or Chocolatey package managers. You can also download the latest Linux, macOS and Windows binaries via the links on the Minisign website.

On any Linux (including WSL), you can compile from source – see the Minisign README for further details of the required commands. Note that there are three prerequisites for compilation: CMake, pkg-config and libsodium. You should be able to install all three of these using your Linux distribution’s package manager. (The package name for libsodium will most likely be libsodium-dev.)

Installing Minisign on SoC Linux Machines

Minisign isn’t available on SoC Linux machines, so you will need to copy the binary manually to your filestore. Note that the Linux binary provided on the Minisign website will not work in the SoC environment! Instead, you should use the version that we’ve compiled. You can download it from the Coursework Prerequisites folder in Minerva, under Assessment and Feedback.

Note: you’ll probably need to set execute permissions on the downloaded file:

chmod u+x minisign

Running Minisign

If you installed via a package manager, then you should be able to enter minisign at a command prompt to run the tool. Running with no arguments will display a usage message, detailing the various command line options.

If you copied the binary manually to a directory in your filestore, you can run it from that directory using ./minisign on Linux & macOS, or just minisign on Windows. To make the binary always available at the command prompt, regardless of which directory you are in, put the binary in a bin subdirectory of your home directory, then add that directory to your PATH.

Generating a Key Pair

  1. Generate a key pair and output the public key to a file, using the following command:

    minisign -G -p key.txt

    The -p option is not strictly required but allows you to choose a filename for the public key (in this case, key.txt). By default, the private key will be written to .minisign/minisign.key, under your home directory.

    If you ever need to generate a new key pair, replacing the old one, add the -f option to the command above.

  2. Examine the contents of key.txt. The first line of this file is a comment, identifying this as a public key and including a unique key ID. The second line of the file contains an encoded version of the public key.

  3. Submit your public key, using the link provided in the Submit My Work folder in Minerva. This will ensure that we can verify any signed files that you submit to us – e.g., coursework submissions.

    Please double-check the file that you submit, to make sure it is your public key, not your private key (or Nick’s public key).

    Keep the public key to help you experiment with signature verification (see below). When you’ve finished this exercise, you can remove it. If you ever need the public key again in future, it can be recovered easily with

    minisign -R -p key.txt

Signing a File

  1. Download song.txt. This is a small text file containing some song lyrics. Examine the file’s contents in a text editor.

  2. Try signing the file with this command:

    minisign -S -m song.txt

    Because this operation involves your private key, you will be prompted to enter the password that you chose when you created the key pair.

  3. The Ed25519 signature for song.txt is in the file song.txt.minisig. Open this file in a text editor. Refer to the Minisign documentation for a full explanation of the file format. Note, in particular, the inclusion of untrusted comments and trusted comments.

    There are, in fact, two signatures in the signature file: one computed for song.txt, and a second ‘global signature’ computed over the first signature and the trusted comment. This means that verification will fail if either the signed file or the trusted comment have been modified. The untrusted comment is not involved in any way in computation of the signature.

    Minisign will pick suitable defaults for the untrusted and trusted comments, but you can override these with comments of your own choosing, using the -c and -t command line options, respectively.

Verifying a Signature

  1. To verify the signature generated for song.txt, enter this:

    minisign -V -m song.txt -p key.txt

    You won’t be prompted for a password here, because the operation involves a public key, not a private key. Minisign should display the message “Signature and comment signature verified”, followed by the trusted comment.

  2. Open song.txt in a text editor. Change the first character, then save the file and try verifying again. This time Minisign should report “Signature verification failed”. Edit song.txt and return it to its original state, then save the file again. Check that the signature now verifies, just as it did before.

  3. Now open song.txt.minisig in a text editor. Change a single character of the untrusted comment, then save the file. You should find that the signature still verifies, because the untrusted comment wasn’t used when computing the signature.

  4. Finally, open song.txt.minisig in a text editor. Change a single character of the trusted comment, then save the file. You should now find that Minisign reports “Comment signature verification failed”.