1gtlssh-keygen(1) General Commands Manual gtlssh-keygen(1)
2
6 gtlssh-keygen - Key handling for gtlssh
7
9 gtlssh-keygen [options] <command> [command options]
10
12 The gtlssh-keygen program is used for making key handling for gtlssh
13 easier.
14 Generally, when you start using gtlssh on a system, you would run
16 gtlssh-keygen keygen
18 and it would create keys for you. You should do the same thing on any
20 target system you want to log into with gtlssh. Then copy the de‐
21 fault.crt file in your $HOME/.gtlssh directory to the target's
22 $HOME/.gtlssh/allowed_certs directory. Then run
23 gtlssh rehash
25 on the target system to generate the hashes After that you should be
27 able to log in without a password.
28 When you need to regenerate your keys, you run
30 gtlssh-keygen keygen
32 again. It will prompt you for replacement. If you replace the keys,
34 the old keys will be saved with a ".1" appended to the filename. Once
35 you replace they keys, you need to push up new keys to all your target.
36 You can run
37 gtlssh-keygen pushcert target1 [target2 [....]]
39 to update they keys on all those targets. It will use the old creden‐
41 tials (with the ".1" appended) to do this, so it should work easily.
42
44 Unlike ssh, ssl keys have lifetimes. By default gtlssh creates 1 year
45 lifetimes on keys, though you can override this. Although this is a
46 little annoying, it is a good idea to replace your keys periodically,
47 so you could call this a good thing.
48 gtlssh lets you create keys for specific targets and use them automati‐
50 cally. Suppose, for instance, that you want to use a different key for
51 logging into target abc.my.domain. You would do:
52 gtlssh-keygen keygen abc.my.domain
54 and it would create a key and certificate in the directory
56 .gtlssh/keycerts with the names abc.my.domain.crt and abc.my.do‐
57 main.key. You would need to copy that certificate (not the de‐
58 fault.crt) to your remote target. gtlssh would see that those keys
59 were there and use them automatically when you logged in to abc.my.do‐
60 main. The pushcert command understands this, too, and will handle
61 pushing the proper keys when you push to abc.my.domain.
62 You can also add ports to the key generation, and it will only use it
64 if you connect to the specific target on the specific port. This could
65 be useful for ser2net.
66
68 gtlsshd will work on Windows, and it will sort of work without a pass‐
69 word, but certain things will not work as the logon has no stored cre‐
70 dentials, and it is unable to create a linked token for admin logins so
71 you can't do admin things.
72 To work around this issue and still allow certificate logins, you can
74 use the storepw command of gtlssh-keygen to store your password in your
75 .gtlssh directory. This is not ideal, but your private keys are there,
76 anyway, so it's not a huge thing. Administrators on your system will
77 be able to look at your password, so be warned.
78
80 --keysize size
81 Create an RSA key with the given number of bits. Default is
82 2048. Usually 1024, 2048, or 4096.
83 --keydays days
85 Create a key that expires in the given number of days. Default
86 is 365.
87 --basedir dir
89 Base directory for gtlssh. Default is $HOME/.gtlssh. Default
90 keys go here.
91 --keydir dir
93 Location to put the non-default generated keys. Default is
94 $HOME/.gtlssh/keycerts for user certificates. For server cer‐
95 tificates it is in sysconfdir (generally /etc) /gtlssh on Unix.
96 On Windows it is the directory of the executable /../etc.
97 --commonname name
99 Set the common name in the certificate. The default is your
100 username for normal certificates and the fully qualified domain
101 name (prefixed with the keyname if the keyname is given) for
102 server certificates.
103 --algorithm algname
105 Use the given algorithm for the key generation, one of rsa or
106 ec. The default is rsa.
107 --force | -f
109 Don't ask any questions, just force the operations. Be careful,
110 this will overwrite data without asking.
111 --version
113 Print the version number and exit.
114 -h|--help
116 Help output
117
119 Commands are:
120 keygen [-p <port>] [hostname]
122 Setup of the base directory (if not already set up) and create
123 keys. If nothing is specified, create the default key in
124 <basedir>/default.key and <basedir>/default.crt. Otherwise cre‐
125 ate keys in the form <keydir>/<host>[,<port>].key and <key‐
126 dir>/<host>[,<port>].crt.
127 setup Like keygen, but take no options and create the default certifi‐
129 cate only.
130 rehash [directory [directory [...]]]
132 The openssl library used by gtlssh requires that certificates in
133 a library be hashed so it can find them. This command redoes
134 the hashes in the given directories. If no directory is speci‐
135 fied, it rehashes <basedir>/allowed_certs and
136 <basedir>/server_certs.
137 Note that if you add keys to these directories, you must rehash
139 them or they will not work.
140 rehash will automatically remove any certificates that have ex‐
142 pired.
143 addallow [-i] <hostname> <file>
145 Add the given file as an allowed public certificate for the
146 given hostname. It will install this file in the directory in
147 <basedir>/allowed_certs with the name "hostname.crt". It will
148 also rehash the directory. If -i is specified, input comes from
149 stdin and the file is not required or used. If the destination
150 file already exists, it will rename it "hostname.crt.1.crt".
151 pushcert [-n <name> ] [-p <port>] <hostname> [[-p <port>] <hostname>
153 [...]]
154 Put the local certificate for the given host onto the remote
155 host so it can be used for login. It uses old credentials (cre‐
156 dentials with .1 appended to the name, per keygen) if they are
157 there. This is useful if you have updated your certificate and
158 need to send a new one to some remote hosts. It finds the cer‐
159 tificate name as described in the keygen command. If old cre‐
160 dentials exist, it will use those to connect with gtlssh and
161 send the certificate. Otherwise it will use default credentials
162 and hope for the best, probably only useful if passwords are ac‐
163 cepcted. This only works one keygen back, if you have run the
164 keygen command twice for the host, you will need to transfer the
165 certificate manually. By default the credential on the remote
166 host is named the output of 'hostname -f' on the local machine,
167 -n overrides this.
168 storepw
170 Windows only, see "WINDOW HACKS" above for details. Prompts for
171 your password to store in your .gtlssh directory.
172 serverkey
174 Create keys for the server, generally in /etc/gtlssh/gtlsshd.key
175 and /etc/gtlssh/gtlsshd.crt. You generally must be root to do
176 this. Use for initial setup of gtlsshd.
177 If you specify a keyname, the common name used for the key will
179 be "<keyname>.<hostname>" by default, unless you set it with
180 --commonname. If you do not specify a keyname (defaulting it to
181 gtlsshd), the common name is just the hostname. This avoids the
182 following problem...
183 NOTE: If you run multiple servers on the same system, you must
185 have a different common name for each one. Some version of
186 openssl will look at another certificate with the same common
187 name as part of the same certificate chain and you will get a
188 failure:
189 authority and subject key identifier mismatch
191 So if, for instance, you are running ser2net and gtlsshd on the
193 same system, they must have different common names.
194
197 gtlssh(1), gtlsshd(8)
198
200 None.
201
203 Corey Minyard <minyard@acm.org>
204Key handling for gtlssh 01/02/19 gtlssh-keygen(1)