sshtoken(1)

SSHTOKEN()

NAME

sshtoken - Generate and apply secure token by signing an object with ssh

SYNOPSIS

sshtoken [-h] [-a | -b] [-k PATTERN | -K KEYFILE] [-n NAME] [-i FILE] [-o FILE] [-s FILE] [-v] [-c CONFIG] [-V] COMMAND

DESCRIPTIION

Generate and apply secure token by signing an object with ssh-keygen.

First, you need ssh-keygen -Y sign to run properly with your keys. Usually it can be done by starting ssh-agent and feeding the key in need to it. See ssh(1) suite documentation to learn how to manipulate SSH keys.

SSH agent has access to your private keys, but you don't need them directly. All we need is agent to sign the unique identifier of the data you want to secure (presumably, the file name). Once the signature is developed, it used to obtain random seed. Finally, a random sequence defined by the seed is XOR-ed with infinitely repeating signature and input data.

Both encryption and decryption is performed symmetrically, the only difference is how to chose the unique name by default. The rule is if not provided, the unique name is the name of secure stream. It is — the name of output when encrypting and the name of input file when decrypting. If the corresponded stream is not a file, the name became "<stream>".

If output stream is a file, a binary output format is used, if not — and «armored ASCII» one (base64 if no native armored format is provided). An explicit format can be set by --armored/--binary option.

By default, the first public key appearing in ssh-add -L list is used for signing, although you can specify a substring to filer out non-matching ones with --key=substring option. The key is also can be read from file with --keyfile option. Again, there is no direct access to private keys, all of the keys used are public.

COMMANDS

encrypt: Encrypt data. Input stream contains insecure data (e. g. credentials to store), output stream is secured by the key. The name, if not given, is taken from output file path.
decrypt: Decrypt data. Input stream contains secure data (e. g. credentials vault content), output stream is sensitive data to use. The name, if not given, is taken from intput file path.
sign: Sign data. Instead of signing the name, sign the data itself, writing signature to the output file. No sensitive data involved in the operation.
verify: Verify signed data. The special case, that has two input streams — the signature and the data itself. At least one of the streams should point to a file by specifying either --input or --signature option. No sensitive data involved in the operation.

OPTIONS

-h, --help: show this help message and exit
-a, --armored: Use armored ASCII format for encrypted file
-b, --binary: Use binary format for encrypted file
-k SUBSTRING, --key SUBSTRING: Use public key from ssh agent matching SUBSTRING given
-K KEYFILE, --keyfile KEYFILE: Read public key from KEYFILE
-n NAME, --name NAME: Use NAME for signing
-i FILE, --input FILE: Read data from FILE
-o FILE, --output FILE: Write data to FILE
-s FILE, --signature FILE: Read signature from FILE
-v, --verbose: Increase verbosity
-c CONFIG, --config CONFIG: Use CONFIG file for default values
-V, --version: show program's version number and exit

FILES

You can use TOML configuration file to define some options. The default file name is $HOME/.config/sshtoken/config.toml, but it can be in turn redefined by specifying --config option.

EXAMPLES

Encrypt data from the standard output (armored format is used and name is set to "<stream>" for no output file is specified):

$ sshtoken encrypt < plain_file > encrypted_file

Decrypt armored data named <stream> from file:

$ sshtoken -a decrypt -n '<stream>' -i encrypted_file

Encrypt and decrypt data with selected key type:

$ sshtoken -k ssh-ed25519 encrypt -i plain_file -o encrypted_file
$ sshtoken -k ssh-ed25519 decrypt -i encrypted_file -o test_file
$ cmp plain_file test_file

Configuration file ~/.config/sshtoken/config.toml example:

key = "ssh-ed25519"

BUGS

For now, no encrypted data consistency check is performed, so it's possible to erroneously decrypt it with the wrong key and get a random trash without an error message. See TODO.md for future plans to improve this and other cases.

DSA/EcDSA keys are unsupported: they generate different signatures for the same data.

The utility relies strongly upon SSH suite execution in Linux/POSIX environment, there's no adaptation to non-NIX operating systems.

AUTHOR

Fr. Br. George <george@altlinux.org>

2025-08-17