ptssh: portable SSH client for Unix
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ptssh is and SSH client (with support for ssh, scp, sftp and rsync) for
Unix with a focus on portability and single-file configs: it has a single
config file (and it ignores ~/.ssh/*), and it works equivalently on any
Unix system and any OpenSSH version. After configuration, it can be used
as a fallback to connect if ssh(1) stops working because of a software
upgrade or a configuration change. It can also be used on public computers
or loaners where reading and writing OpenSSH config files is not desired.
ptssh is implemented as a Bourne shell script calling OpenSSH ssh(1) with
custom options. The config file can be embedded to the ptssh script and
the merged standalone script can be copied to a pen drive and used on
another computer (running Unix and having OpenSSH installed).
Introduction
~~~~~~~~~~~~
To start using ptssh, you need to create the config file ~/.ptssh first.
This config file contains the user identity (private key), and for each
server the server hostkey, server connection information (hostname, port,
username) and server X11 forwarding config. The easiest way to create a
config file is importing from ssh(1), e.g. `./ptssh import myserver1' and
`./ptssh import myuser@myserver2'. It's possible to import multiple times
if the user identity (private key) is the same; in this case subsequent
imported server specifications will be appended to the config file
~/.ptssh. A sample config file is also provided in the file
`config.ptssh.sample'. (See details below.)
Design goals of ptssh (all met):
* It should work with old and new versions of OpenSSH. More specifically,
OpenSSH 3.9 (released on 2004-08-18) or later, and
Debian Etch (released on 2007-04-08) or later should work.
* It should work with many Bourne shells.
* The ptssh-keycat tool should work with old and new versions of Perl 5.
More specifically, Perl 5.6.1 (released on 2001-04-08) or later should
work.
* It should ignore OpenSSH system config files in /etc/ssh/* .
* It should ignore OpenSSH user config files in ~/.ssh/* . The reason for
this is portability to other systems: by copying the ptssh shell script
and the config file ~/.ptssh, it should work equivalently on the target
system.
* It should ignore the ssh-agent(1). This is also part of portability.
* It should be easy to embed the config into the ptssh script, thus
copying one file to the target system should be enough.
* It shouldn't attempt to run any command (other than ssh, scp, sftp, rsync
and chmod) which isn't a shell builtin. (Actually it also runs chmod(1) to
pacify permission checks by OpenSSH on user identity files.)
It's possible to embed the config into the ptssh script by just
concatenating them:
$ cat ptssh ~/.ptssh >ptssh_embedded
$ chmod +x ptssh_embedded
$ ./ptssh_embedded myserver1 # Example call.
However, it's better to use ptssh-keycat for concatenation, because it
also does the necessary key conversion. Native OpenSSH private key format
(-----BEGIN OPENSSH PRIVATE KEY-----) only works if the key is at the
beginning of the file (ssh(1) error message: `Load key "...": invalid
format'), and ptssh-keycat converts them to an OpenSSL-compatible format,
which works anywhere. Do it like this:
$ ./ptssh-keycat -x ptssh_embedded ptssh ~/.ptssh
$ ./ptssh_embedded myserver1 # Example call.
Then `./ptssh_embedded ...' won't read ~/.ptssh, but it would use the
embedded user identity and server specifications.
A limitation of embedding: the user identity must be an RSA (ssh-rsa,
recommended with 4096 bits) or DSA (ssh-dss) private key in an
OpenSSL-compatible format. Other key algorithms (e.g. ssh-ed25519) won't
work for embedding, because OpenSSH can't read them in an
OpenSSL-compatible format.
Compatibility notes
~~~~~~~~~~~~~~~~~~~
ptssh is very portable: it uses RSA hostkeys by default, and it works with
OpenSSH >=3.8 (checked with OpenSSH 8.2, OpenSSH 7.4, OpenSSH 3.8.1, and
OpenSSH_4.3p2 Debian-9etch3, OpenSSL 0.9.8c 05 Sep 2006 on Debian Etch,
OpenSSL 0.9.7e on Debian Sarge), no matter what the system defaults and
user defaults for the SSH client are. It also works with various Bourne
shells: bash, zsh, dash, pdfksh, busybox sh (ash), posh.
ptssh is compatible with OpenSSH >=3.8 client (released 2004-02-34), but
it's recommended to upgrade to OpenSSH >=3.9 client (released 2004-08-18),
because recent OpenSSH server versions don't support any kex (key
exchange) algorithm compatible with the OpenSSH 3.8 client, with the
client failing with error `no kex alg'. ptssh is also compatible
with newer OpenSSH clients, e.g. 8.2 (released 2020-02-14).
ptssh ignores the ssh-agent, and asks for the identity file passphrase
each time. This is on purpose. The goal is to make to ptssh run
independently and identically on any system and environment (given the
same config file), and the use of ssh-agent would introduce variance.
ptssh is also compatible with Debian Sarge (2005-06-06) or later, but
recent OpenSSH server versions don't support any kex algorithm compatible
with the OpenSSH 3.8.1 client in Debian Sarge, so it's recommended to
upgrade to Debian Etch (2007-04-08) instead, which has OpenSSH 4.3.
ptssh is compatible with rsync >=2.6.4 client in Debian Sarge
(2005-06-06). Maybe it works with even older versions of rsync.
ptssh can't run from a FAT filesystem (or other non-Unix filesystems),
because `chmod' below isn't able to remove rwx permissions for group and
other there. This can be a problem if it's run from USB pen drives.
Private key generation and conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The RSA public key algorithm is recommended for maximum backwards
compatibility with OpenSSH clients and servers. The RSA key size of 4096
bits is high enough to withstand cryptographic attacks in 2021.
You need an OpenSSL-compatible private key if you wish to embed the config
file to the shell script later. OpenSSH only supports RSA and DSA as public
key algorithms in OpenSSL-compatible format. The RSA algorithm is
recommended. The DSA algorithm, as used with by OpenSSH, is now considered
insecure, it's too easy to crack the key on modern hardware. If you don't
need want to embed, any public key algorithm (such as ED25519) will work,
provided that both the OpenSSH client and server support it.
Key generation commands:
* Run this to generate a new, OpenSSH-format, strongly passphrase-protected
RSA private key (user identity) into file id_rsa and public key into file
id_rsa.pub (it won't work when embedded to the shell script):
$ ssh-keygen -t rsa -b 4096 -o -C '' -f id_rsa
Above the `-o' flag of ssh-keygen selects the new, OpenSSH format.
* Alternatively, run this to generate a new, OpenSSH-format, strongly
passphrase-protected ED25519 private key (user identity) into file
id_ed25519 and public key into file id_ed25519.pub (it won't work when
embedded to the shell script):
$ ssh-keygen -t ed25519 -o -C '' -f id_rsa
* Run this to generate a new, OpenSSL-compatible, strongly
passphrase-protected RSA private key (user identity) into file id_rsa and
public key into file id_rsa.pub (it will work when embedded to the shell
script):
$ ssh-keygen -t rsa -b 4096 -C '' -P '' -f id_rsa.unprotected
$ ./ptssh-keycat --protect -o id_rsa id_rsa.unprotected
$ rm -f id_rsa.unprotected
Alternatively, you can do it with openssl(1):
$ openssl genrsa 4096 | ./ptssh-keycat --protect -o id_rsa
$ ssh-keygen -y -f id_rsa >id_rsa.pub
Alternatively, you can do it with openssl(1) only, without using ptssh-keycat:
$ openssl genrsa 4096 |
openssl pkcs8 -out id_rsa -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA1 -iter 4200000
$ ssh-keygen -y -f id_rsa >id_rsa.pub
The private key file id_rsa will start with `-----BEGIN ENCRYPTED PRIVATE
KEY-----'. It will work with both OpenSSH (>=3.8, probably even earlier)
and OpenSSL.
Please note that it's possible to have password-protected RSA and DSA
private keys in the traditional OpenSSL formats (`----BEGIN RSA PRIVATE
KEY-----'; and `----BEGIN DSA PRIVATE KEY-----'), but those are insecure
(weak), because they generate the decryption key by doing a single MD5
digest call, and thus the attacker can try (brute-force) millions of
passphrases per second. The alternative above (`openssl pkcs8
... -iter 4200000') uses PBKDF2 with a sufficiently large iteration count
(equivalent to `ssh-keygen -a 400') to protect against brute-force
attacks.
Key conversion commands:
* Run this to convert a private key in file id_rsa from any format (e.g.
OpenSSL-compatible) to the new, OpenSSH format:
$ ssh-keygen -p -o -f id_rsa
You will have to type the old passphrase (if any) and the new passphrase.
To get an unprotected private key, set the new passphrase to empty.
Above the `-o' flag of ssh-keygen selects the new, OpenSSH format.
* Run this to convert a private key in file id_rsa from any format (e.g.
new, OpenSSH) with public key algorithm RSA or DSA to the
OpenSSL-compatible format, with strong passphrase protection:
$ ./ptssh-keycat --protect -o id_rsa.protected id_rsa
$ mv id_rsa.protected id_rsa
ptssh-keycat is a Perl script which implements most of the conversion
steps natively in Perl, and it uses ssh-keygen(1) and openssl(1) for
passphrase-protection.
Alternatively, it's possble to convert an unprotected private key from the
new, OpenSSH format to the OpenSSL-compatible format with strong
passphrase protection, using puttygen(1) instead of ptssh-keycat. (Please
note that openssl(1) and ssh-keygen(1) together can't do it, either
puttygen(1) or ptssh-keycat is also needed.) (Please note that puttygen(1)
cannot read passphrase-protected private keys in the new, OpenSSH format,
but ptssh-keycat can.) On Debian and Ubuntu, install puttygen(1) with
`sudo apt-get install putty-tools'. Probably it's more convenient to use
ptssh-keycat, because that works without installation. Here is how to
convert using puttygen(1):
$ puttygen -P -O private-openssh -o id_rsa.unprotected id_rsa
Enter passphrase to load key:
Enter passphrase to save key: (specify empty passphrase)
Re-enter passphrase to verify: (specify empty passphrase)
$ openssl pkcs8 -out embed.pem -in id_rsa.unprotected -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA1 -iter 4200000
Enter Encryption Password:
Verifying - Enter Encryption Password:
$ rm -f id_rsa.unprotected
$ chmod 600 id_rsa
* Run this to convert a private key in file id_rsa from any format (e.g.
new, OpenSSH) with public key algorithm RSA or DSA to the
OpenSSL-compatible format, without passphrase protection (unprotected):
$ ./ptssh-keycat --unprotect -o id_rsa.unprotected id_rsa
$ mv id_rsa.unprotected id_rsa
Alternatively, run this to convert an unprotected private key from the
new, OpenSSH format to the OpenSSL-compatible format:
$ puttygen -P -O private-openssh -o id_rsa.unprotected id_rsa
Enter passphrase to load key:
Enter passphrase to save key: (specify empty passphrase)
Re-enter passphrase to verify: (specify empty passphrase)
$ mv id_rsa.unprotected id_rsa
$ chmod 600 id_rsa
* Run this to convert a private key in file id_rsa from any format (e.g.
new, OpenSSH) with public key algorithm RSA or DSA to the
OpenSSL-compatible format, keeping protection unchanged:
$ ./ptssh-keycat -o id_rsa.converted id_rsa
$ mv id_rsa.converted id_rsa
Some other useful commands:
* Run this to replace the private key in the config file ~/.ptssh with the
private key in the file id_rsa:
$ (cat id_rsa &&
perl -ne 'if(/^-----(?:BEGIN|(END)) /){$c-=1-2*!$1}else{print if!$c}' ~/.ptssh
) >~/.ptssh.new
$ cat ~/.ptssh.new >~./ptssh
$ rm -f ~./ptssh.new
Alternatively, you can do it in a text editor. The old private key starts
with the first `----BEGIN ' in ~/.ptssh .
* Run this to enable a private key id_rsa (also works with ~/.ptssh) on the
OpenSSH server:
$ (PK="$(ssh-keygen -y -f id_rsa)"; echo "$PK" |
ssh myserver1 'test -d .ssh || mkdir .ssh; cat >>.ssh/authorized_keys')
The config file
~~~~~~~~~~~~~~~
The config file can be embedded in a merged standalone script by
concatenating the ptssh script with the config file, or it can
be in a separate file, ~/.ptssh.
The format of the config file is the following:
* (Most users don't need to care about these details, because they have
created the config file with `./ptssh import ...'.)
* (Use `./ptssh-keycat --check ~/.ptssh' to check the config for common
errors and incompatibilities with OpenSSH.)
* The beginning of the config file is ignored. This enables embedding the
config to the shell script. Please note that for this to work with the
OpenSSH client, the key type must be OpenSSL-compatible (i.e. anything
other than `-----BEGIN OPENSSH PRIVATE KEY-----'). Only lines starting
with `-----BEGIN ' and `ptssh-hostkey-' are recognized, everything else is
ignored.
* A line of the form `-----BEGIN ... PRIVATE KEY-----' (including
`-----BEGIN PRIVATE KEY-----') indicating the
beginning of the user identity (private key). Any format (`...')
supported by OpenSSH works. It can be protected (encrypted with a
passphrase) or unprotected. Any key algorithm supported by OpenSSH (e.g.
ssh-rsa, ssh-dss, ssh-ed25519) works.
* Optional `Key: value' lines if it's an encrypted traditional OpenSSL RSA
or DSA private key. Example key: `Proc-Type' and `DEK-Info'.
* Base64-encoded private key material.
* A line of the form `-----END ... PRIVATE KEY-----'.
* Comment lines and server specification lines. At least 1 server
specification line. Each line which doesn't start with `ptssh-hostkey-'
is a comment line.
* A server specification line is a whitespace-separated (can be space, tab
or combination) of these items:
* `ptssh-hostkey-ID'. `ID' is an arbitrary unique ID within the file.
* hostkey algorithm. Examples: ssh-rsa, ssh-dss, ssh-ed25519,
ecdsa-sha2-nistp521, ecdsa-sha2-nistp384, ecdsa-sha2-nistp256.
* hostkey public key, Base64-encoded. Starts with `AAAA'.
* server username.
* server port number. The default, 22, also has to be specified.
* server hostname (or IP address).
* X11 forwaring specification. One of: -x (disabled), -X (enabled,
untrusted), -Y (enabled, trusted). If you don't want to run GUI programs
on the server over the SSH connection, specify `-x'.
* host aliases. Comma-separated list of aliases (`Host' lines in
~/.ssh/config) ptssh should recognize in the command-line. By default,
there is only 1 alias: `ID' above.
The config file format was designed with the following requirements:
* It is a structured text file which is easy to generate and parse
from shell scripts.
* It is easy to edit manually, including the copy-pasting of keys
from other files. However, manual config file editing is only an expert
use case: for most uses the config file created by tools ptssh and
ptssh-keycat should be sufficient.
* It can be used for `ssh -o IdentityFile=...' (and `ssh -i ...') without
modification, thus it starts with a private key understood by
OpenSSH, thus starting with `-----BEGIN ... PRIVATE KEY-----'.
Please note that if the config file is embedded within the ptssh script,
then the script (starting with `#! /bin/sh --') comes first. This is
not a problem, because for OpenSSL-compatible private key formats
(i.e. anything other than ``-----BEGIN OPENSSH PRIVATE KEY-----'),
OpenSSH accepts a private key starting anywhere in the file.
* It can be used for `ssh -o UserKnownHostsFile=...' without modification.
This isn't an important restriction, because OpenSSH ignores lines
not starting with with `...' specified in `ssh -o HostKeyAlias=...'.
TODOs
~~~~~
* Use a one-off ssh-agent with the private key piped using ssh-add. This
will lift the following restrictions:
* The new, OpenSSH-format private keys cannot be embedded (because OpenSSH
client only looks at the beginning of the file).
* The ~/.ptssh config file and the embedded shell script must be chmodded
to remove all group and other permission bits. (This will also make the
embedded ptssh shell script work on FAT and exFAT filesystems.)
* Add support for multiple ptssh config files (`ptssh -F <config-file>
...').
* Add support for convenient and permanent ssh-agent dedicated to ptssh,
one ssh-agent per private key (config file). Agent forwarding can be
enabled, but keys in the ssh-agent will be immutable after the first
key has been added.
__END__