gtlssh-keygen - Key handling for gtlssh
gtlssh-keygen [options] <command> [command
options]
The gtlssh-keygen program is used for making key handling
for gtlssh easier.
Generally, when you start using gtlssh on a system, you would
run
gtlssh-keygen keygen
and it would create keys for you. You should do the same thing on
any target system you want to log into with gtlssh. Then copy the
default.crt file in your $HOME/.gtlssh directory to the target's
$HOME/.gtlssh/allowed_certs directory. Then run
gtlssh rehash
on the target system to generate the hashes After that you should
be able to log in without a password.
When you need to regenerate your keys, you run
gtlssh-keygen keygen
again. It will prompt you for replacement. If you replace the
keys, the old keys will be saved with a ".1" appended to the
filename. Once you replace they keys, you need to push up new keys to all
your target. You can run
gtlssh-keygen pushcert target1 [target2 [....]]
to update they keys on all those targets. It will use the old
credentials (with the ".1" appended) to do this, so it should work
easily.
Unlike ssh, ssl keys have lifetimes. By default gtlssh creates 1
year lifetimes on keys, though you can override this. Although this is a
little annoying, it is a good idea to replace your keys periodically, so you
could call this a good thing.
gtlssh lets you create keys for specific targets and use them
automatically. Suppose, for instance, that you want to use a different key
for logging into target abc.my.domain. You would do:
gtlssh-keygen keygen abc.my.domain
and it would create a key and certificate in the directory
.gtlssh/keycerts with the names abc.my.domain.crt and abc.my.domain.key. You
would need to copy that certificate (not the default.crt) to your remote
target. gtlssh would see that those keys were there and use them
automatically when you logged in to abc.my.domain. The pushcert command
understands this, too, and will handle pushing the proper keys when you push
to abc.my.domain.
You can also add ports to the key generation, and it will only use
it if you connect to the specific target on the specific port. This could be
useful for ser2net.
- --keysize
size
- Create an RSA key with the given number of bits. Default is 2048. Usually
1024, 2048, or 4096.
- --keydays
days
- Create a key that expires in the given number of days. Default is
365.
- --basedir
dir
- Base directory for gtlssh. Default is $HOME/.gtlssh. Default keys go
here.
- --keydir
dir
- Location to put the non-default generated keys. Default is
$HOME/.gtlssh/keycerts
- --commonname
name
- Set the common name in the certificate. The default is your username for
normal certificates and the fully qualified domain name for server
certificates.
- --force | -f
- Don't ask any questions, just force the operations. Be careful, this will
overwrite data without asking.
- -h|--help
- Help output
Commands are:
- keygen [-p
<port>] [hostname]
- Setup of the base directory (if not already set up) and create keys. If
nothing is specified, create the default key in
<basedir>/default.key and <basedir>/default.crt. Otherwise
create keys in the form <keydir>/<host>[,<port>].key and
<keydir>/<host>[,<port>].crt.
- setup
- Like keygen, but take no options and create the default certificate
only.
- rehash [directory
[directory [...]]]
- The openssl library used by gtlssh requires that certificates in a library
be hashed so it can find them. This command redoes the hashes in the given
directories. If no directory is specified, it rehashes
<basedir>/allowed_certs and <basedir>/server_certs.
Note that if you add keys to these directories, you must
rehash them or they will not work.
rehash will automatically remove any certificates that
have expired.
- addallow [-i]
<hostname> <file>
- Add the given file as an allowed public certificate for the given
hostname. It will install this file in the directory in
<basedir>/allowed_certs with the name "hostname.crt". It
will also rehash the directory. If -i is specified, input comes
from stdin and the file is not required or used. If the destination file
already exists, it will rename it "hostname.crt.1.crt".
- pushcert [-n
<name> ] [-p <port>] <hostname> [[-p <port>]
<hostname> [...]]
- Put the local certificate for the given host onto the remote host so it
can be used for login. It uses old credentials (credentials with .1
appended to the name, per keygen) if they are there. This is useful if you
have upated your certificate and need to send a new one to some remote
hosts. It finds the certificate name as described in the keygen command.
If old credentials exist, it will use those to connect with gtlssh and
send the certificate. Otherwise it will use default credentials and hope
for the best, probably only useful if passwords are accepcted. This only
works one keygen back, if you have run the keygen command twice for the
host, you will need to transfer the certificate manually. By default the
credential on the remote host is named the output of 'hostname -f' on the
local machine, -n overrides this.
- serverkey
- Create keys for the server, generally in /etc/gtlssh/gtlsshd.key and
/etc/gtlssh/gtlsshd.crt. You generally must be root to do this. Use for
initial setup of gtlsshd.
Corey Minyard <minyard@acm.org>