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

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