NAME

       gtlssh-keygen - Key handling for gtlssh

SYNOPSIS

       gtlssh-keygen [options] <command> [command options]

DESCRIPTION

       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.

DIFFERENCES FROM SSH

       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.

WINDOWS HACKS

       gtlsshd  will  work  on Windows, and it will sort of work without a password, but certain things will not
       work as the logon has no stored credentials, and it is unable to create a linked token for  admin  logins
       so you can't do admin things.

       To  work around this issue and still allow certificate logins, you can use the storepw command of gtlssh-
       keygen to store your password in your .gtlssh directory.  This is not ideal, but your  private  keys  are
       there,  anyway,  so  it's  not  a huge thing.  Administrators on your system will be able to look at your
       password, so be warned.

OPTIONS

       --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  for  user
              certificates.   For  server certificates it is in sysconfdir (generally /etc) /gtlssh on Unix.  On
              Windows it is the directory of the executable /../etc.

       --commonname name
              Set the common name in the certificate.  The default is your username for normal certificates  and
              the  fully  qualified  domain  name (prefixed with the keyname if the keyname is given) for server
              certificates.

       --algorithm algname
              Use the given algorithm for the key generation, one of rsa or ec.  The default is rsa.

       --force | -f
              Don't ask any questions, just force the operations.  Be careful, this will overwrite data  without
              asking.

       --version
              Print the version number and exit.

       -h|--help
              Help output

COMMAND

       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 updated 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.

       storepw
              Windows  only,  see  "WINDOW  HACKS" above for details. Prompts for your password to store in your
              .gtlssh directory.

       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.

              If you specify a keyname, the common name used for  the  key  will  be  "<keyname>.<hostname>"  by
              default,  unless  you set it with --commonname.  If you do not specify a keyname (defaulting it to
              gtlsshd), the common name is just the hostname.  This avoids the following problem...

              NOTE: If you run multiple servers on the same system, you must have a different  common  name  for
              each  one.   Some version of openssl will look at another certificate with the same common name as
              part of the same certificate chain and you will get a failure:

                authority and subject key identifier mismatch

              So if, for instance, you are running ser2net and gtlsshd  on  the  same  system,  they  must  have
              different common names.

SEE ALSO

       gtlssh(1), gtlsshd(8)

KNOWN PROBLEMS

       None.

AUTHOR

       Corey Minyard <minyard@acm.org>

Key handling for gtlssh                             01/02/19                                    gtlssh-keygen(1)