home | help 
gtlssh-keygen(1)	     General Commands Manual		gtlssh-keygen(1)

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 eas-
     ier.

     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 tar-
     get 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/al-
     lowed_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 re-
     place 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 automati-
     cally.  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 certifi-
	    cates it is in sysconfdir (generally /etc) /gtlssh on Unix.  On Win-
	    dows it is ../etc/gtlsshd from the directory of the executable.

	    Note that on Windows, you must set the permissions of the key direc-
	    tory (or the keys) so that only System and Administrators  have  ac-
	    cess.   Otherwise  gtlsshd will fail with an error about permissions
	    on the key.

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

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

     --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>/de-
	    fault.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 al-
	    ready 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  de-
	    scribed  in  the  keygen command.  If old credentials exist, it will
	    use those to connect with gtlssh and send the  certificate.   Other-
	    wise 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 cre-
	    dential  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  --common-
	    name.   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.

	    On Windows, you must remove all permissions from the key file except
	    for  SYSTEM  and  Administrator.  If gtlssh doesn't run, this is the
	    first thing to check.  (You can raise get a SYSTEM	console  as  de-
	    scribed  below  and  run  "gtlssh -d" and it will give you an error,
	    this is useful for debugging.)  The program doesn't yet do	this  by
	    default, unfortunately.  You will have to configure the file as SYS-
	    TEM to do this.  The procedure is:

	    Run an administrator console.

	    Run "psexec -sid cmd" to run a console as SYSTEM.

	    Run "explorer".

	    Go	to the key file in explorer, right click on it, and choose Prop-
	    erties, then Security, then you can modify it from there.

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)
home | help