Skip to content

Latest commit

 

History

History
155 lines (107 loc) · 7.66 KB

README.md

File metadata and controls

155 lines (107 loc) · 7.66 KB
Raw

Description

Welcome to Songe.

Songe (pronounced "songe") is a naive file signer and verifier tool, designed to sign files in a per-project context: each project directory can have its own keys to directly sign project files. Songe currently uses RbNaCl, which uses the excellent libsodium. A light version, Songev, only allow to quick verify signatures, doesn't use RbNaCl, but use the light Ruby Ed25519 library.

Verify and sign files are made with Ed25519 32-bytes keys using SHA-512. The signing key (base32-encoded starting with 'K') is encrypted with the user passphrase before saved on disk. The verify key (base32-encoded starting with 'P') is joined to the signing key saved on disk and to all signatures (so to verify a file, you just need the file and the signature .sgsig file). Key pair is saved into a local .songe.key file.

Trusted recipients' verifying keys may be added to a trusted keys list saved to a .songe.trust local file to add confidence when verifiyng files signed by them. The trusted keystore is managed by songe commands and signed at each editing access by the personal signing key. Although the trust keystore is signed, it is up to the user to check whether the recipient's key belongs to the recipient.

.songe.key and .songe.trust are stored in the local directory when generated (and when password is changed)). At usage time, the key is looked up in: 1. the local directory, 2. the $SONGE_HOME directory and 3. the user $HOME directory. This way, each project can have its own songe key, or there can be an unique songe key for all projects.

Features and benefits

  • Sign and verify files easily with Ed25519 keys (detached or embedded signatures)
  • Manage a simple keystore of trusted recipients public keys for secure verifications
  • Dead simple to use (sign and verify) and yet very secure (based on RbNaCl/libsodium)
  • Possibility to attach a comment to the signature (will be signed as well)
  • No need to get/share the verify key to verify a file (included in signature)
  • Very small and user-friendly signature files (comment, datetime and signature in Yaml format)

Installation

Songe is written in Ruby, and requires it to run. You will also need to install the following libraries / ruby gems:

For the full version songe

# run as admin
apt install libsodium23
gem install rbnacl digest-crc highline base32 strong_password

On Ubuntu, for example, you can install the libraries by running:

rake install

For the light (verify only) version songev

# run as admin
gem install ed25519 digest-crc base32

songe and songev are executable Ruby script files. They should be placed into a PATH-indexed system or user bin/ directory. On Unix-like systems, make sure that they are marked as executable (chmod +x songe songev), or run them as arguments of the Ruby command (example: ruby songe -s file).

Simple usage examples

  # Generate a new signing key (writes the key to `./.songe.key`)
  # The first asks to choose a passphrase, the second generates a secure one
  songe --generate
  songe --secure --generate

  # Or import an existing signing key (then paste the key KABCDE...)
  songe --import-key

  # With a signing key available, display the verification key
  songe --verifkey
  # ... or even the signing key (then enter the passphrase)
  songe --signkey

  # Sign a file with the new key (writes the signature to `./myfile.txt.sgsig`)
  # The third signs with a signed comment, the fourth makes an embedded signature
  songe --sign 'myfile.txt'
  songe --verbose --sign 'myfile.txt'       # displays more information
  songe --message 'first release' --sign 'myfile.txt'
  songe --embed --sign 'myfile.txt'
  # Real example of embedded signature (only share the file `SHASUM.sgsig`)
  sha256sum files.* > SHASUM && songe --embed --sign SHASUM && rm SHASUM

  # Add the sender verify key to the trusted list (please use a full string key)
  songe --add-key PABCDE...FGHIJK
  # Yes you can manage the trusted keystore
  songe --trusted             # lists all trusted keys
  songe --trusted ABCD        # lists trusted keys containing `ABCD`
  songe --del-key PABCDE...   # deletes the key from the trusted list

  # Verify a downloaded file `yourfile.txt` (signature is `./yourfile.txt.sgsig`)
  songe --verify 'yourfile.txt'
  songe --verbose --verify 'yourfile.txt'   # displays more information
  # Or verify an embedded signature
  songe --verify 'yourfile.txt'             # yes, it is the same command
  # And for the songev version
  songev 'yourfile.txt'
  # Real example of embedded signature (you only got one file `SHASUM.sgsig`)
  songev SHASUM | sha256sum --check      # yes, that's all!

Questions

  • Should I use songe or songev ?

If you can (and want to) install libsodium, then use songe, otherwise or if you just have to verify signatures, use songev.

  • Here is said that I can add the recipient's verify key to a trusted keystore. Do I need it to verify a signature?

No, for the verification, you do not need the verify key, since it is already included in the signature file .sgsig. Adding the key to the trusted keystore is only an additional layer of security: it allows you to check the sender's key trust level only once.

  • I sign a file in embedded signature (--embed option), and the verification fails. Why?

For security reasons, the verification first checks if a file without .sgsig extension exists, and if not, uses the embedded data in signature file. So checking an embedded signature requires that no original file name remains in the same directory (example: after signing the SHASUM file in embedded mode, a SHASUM.sgsig file is created containing the signed data, so please remove the original SHASUM file).

Check scripts integrity

First, commits are signed with my PGP key 466F B094 B95C 3589 and are automatically verified by GitHub. Second, the release songe-x.x.x.zip itself is OpenPGP-signed with the same key.

Additionally, songe and songev files SHA-256 sums are computed and the sums are then clear-signed with Songe itself. You can choose to only verify sums, or sums with sums signatures. The commands below apply to the Unix-like environments.

To only verify SHA-256 sums:

grep ' songe' SHASUM.asc | sha256sum -c

To verify sums as well as sums signature with Songe itself (key PCINJUEXO6IVL44 PCINJUEXO6IVL44KLEBNTXG7GMHWVNAAOOUVZTXC5R7KAT67DTKXX3CO):

rake verify

or

songev SHASUM | sha256sum -c

Note that you can then add my key in your personal trust keystore after generating your key 🙂

songe --generate
songe --add-key PCINJUEXO6IVL44KLEBNTXG7GMHWVNAAOOUVZTXC5R7KAT67DTKXX3CO

License

Micaël P. - Distributed under the MIT License. See LICENSE for further details.

If you like Songe, please remember it's maintained in my free time, and... buy me a coffee ❤️