The Command Line API¶

The command line interface supports 5 different subcommands: generate, sign, and verify, which generate keys, sign files, and verify files respectively, and public-key and private-key which simply print out the relevant key for you to make use of it.

Generating Keys¶

If you’re just planning on using Aletheia to verify the origin of a file, then you don’t need to generate keys. This command is only for cases when you want to sign a file.

Generation is easy though, as Aletheia takes the complication out of the process. All you have to do is:

$ aletheia generate

That’s it. After a few moments, Aletheia will generate new public and private keys and store them in ${HOME}/.config/aletheia/ by default. The private and public keys will be named aletheia.pem and aletheia.pub respectively.

Changing the Default Home Directory¶

By default, Aletheia assumes that you want all of your Aletheia-related files stuffed into ${HOME}/.config/aletheia/, but you can change that if you like by setting ALETHEIA_HOME in your environment:

$ ALETHEIA_HOME="/path/to/somewhere/else" aletheia generate

Signing¶

Once you have some keys generated, you can use them to sign files with the sign subcommand. Importantly signing requires two things:

The path to the file you want to sign.
The domain to which you’re attributing the origin of the file.

$ aletheia sign /path/to/file.jpg example.com

What we’re doing here is writing some instructions to your file that (a) claim authoriship of the file, and (b) tell people where they can find the public key that proves that authorship. This means that your public key must always be available at that domain (either via DNS or at https://example.com/aletheia.pub) for verification to work.

Domain in the Environment¶

In cases where you might want to sign a lot of files and don’t want to have to specify the domain name in every case (it’s likely to be the same every time after all), you can specify the domain in your environment:

$ export ALETHEIA_DOMAIN=example.com
$ aletheia sign /path/to/file.jpg
$ aletheia sign /path/to/file.mkv
$ aletheia sign /path/to/file.html

Verification¶

Verification is easy, but note that it might require an internet connection as Aletheia will attempt to fetch the public key (based on the domain in the signed file) if it hasn’t cached it already. By now, you can probably guess what the command looks like:

$ aletheia verify /path/to/file.jpg
$ aletheia verify /path/to/file.mkv
$ aletheia verify /path/to/file.html

That’s all there is to it.

Getting Your Public & Private Keys¶

Aletheia provides a handy interface for reading your public & private keys so you can copy/paste the text somewhere useful.

Your Private Key¶

You can get your private key with the private-key subcommand:

$ aletheia private key
-----BEGIN RSA PRIVATE KEY-----
MIISKQIBAAKCBAEA0qKTDRq/sPsLLZ+C+kr2eONfKYUZFYYNJ+if2oMKqj8pXr4s
J6qG8Z3FBMlcvx9gmKslByUv68DbGVrH/zBdEU+/XOI3cCqn1+Pblz0r2UDgl97z
7xThq3y6CA1NvI36kcipuzA1HOTMXVdb4voG095CbRo96K+eLXtLpYSvAkzZTCCa
O2UZTcAdb0Nc+BUB3c9GWioLSXADgJKjaqZGMGEGuOKEsHovXc3t+9yNm4Q4YlBl
...

Your Public Key¶

Your public key can be recognised in either PKCS1 format or OpenSSH format. Handily, you can use the public-key subcommand to get your key in either format.

To see the default PKCS1 format, you can call public-key without any options, or with --format pkcs1:

$ aletheia public-key
-----BEGIN RSA PUBLIC KEY-----
MIIECgKCBAEA0qKTDRq/sPsLLZ+C+kr2eONfKYUZFYYNJ+if2oMKqj8pXr4sJ6qG
8Z3FBMlcvx9gmKslByUv68DbGVrH/zBdEU+/XOI3cCqn1+Pblz0r2UDgl97z7xTh
q3y6CA1NvI36kcipuzA1HOTMXVdb4voG095CbRo96K+eLXtLpYSvAkzZTCCaO2UZ

For OpenSSH format, use --format openssh:

$ aletheia public-key --format openssh
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAEAQDSopMNGr+w+wstn4L6SvZ4418phRkVhg...