Chrome Version       : <Copy from: 'about:version'>
URLs (if applicable) :Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	1	```
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	2	                            .--~~~~~~~~~~~~~------.
3	                           /--===============------\
4	                           | |```````````````|     |
5	                           | |               |     |
6	                           | |      >_<      |     |
7	                           | |               |     |
8	                           | |_______________|     |
9	                           |                   ::::|
10	                           '======================='
11	                           //-"-"-"-"-"-"-"-"-"-"-\\
12	                          //_"_"_"_"_"_"_"_"_"_"_"_\\
13	                          [-------------------------]
14	                          \_________________________/
15	
Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	16	                            hterm and Secure Shell
17	                          Frequently Asked Questions
18	```
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	19	[TOC]
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	20	
21	Hello World.  This is the hterm/Secure Shell FAQ.  If you have a question that
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	22	is not answered here, please ask it on the [chromium-hterm mailing list].
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	23	
24	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	25	## General Questions
26	
27	
28	### What is "Secure Shell"?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	29	
30	  Secure Shell is a Chrome Application that combines the "ssh" command (see
Mike Frysinger	c766247	2017-04-08 03:35:47	[diff] [blame]	31	  https://www.openssh.com/ for details) ported to NativeClient with the "hterm"
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	32	  terminal emulator to provide a secure shell client for the Chrome browser.
33	
34	  Secure Shell provides similar functionality to PuTTY on Microsoft Windows(c)
35	  systems, and the ssh command-line application on Mac OS X and Linux systems.
36	
37	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	38	### What is "hterm"?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	39	
40	  "HTML Terminal", or hterm, is an xterm-compatible terminal emulator written
41	  entirely in JavaScript.
42	
43	  It is intended to be fast enough and correct enough to compete with native
44	  terminals such as xterm, gnome-terminal, konsole and Terminal.app.
45	
46	  hterm is only a terminal emulator.  It does not provide SSH access (or any
47	  other text-based command) on its own.
48	
49	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	50	### How do Secure Shell and hterm relate to the "crosh" (Ctrl-Alt-T) command in Chrome OS?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	51	
Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	52	  See [chromeos-crosh.md](chromeos-crosh.md) in this directory for the details.
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	53	
54	  TL;DR - Don't use crosh for ssh any more, use the Secure Shell app instead.
55	  The crosh shell will use the newer terminal emulator from Secure Shell when
56	  possible.
57	
58	
Mike Frysinger	6266598	2017-12-17 06:26:39	[diff] [blame]	59	### What's the difference between the Secure Shell App and Extension? {#app-vs-ext}
60	
61	  [Chrome Apps](https://developer.chrome.com/apps/about_apps)
62	  [were launched](https://blog.chromium.org/2013/02/chrome-app-launcher-developer-preview.html)
63	  to create applications using web technology that would work like native apps
64	  on any platform Chrome runs on.  Secure Shell was built on that technology.
65	
66	  Fast forward a few years and
67	  [Chrome Apps were deprecated](https://blog.chromium.org/2016/08/from-chrome-apps-to-web.html)
68	  on all non-Chrome OS platforms.  That means the Secure Shell App would only
69	  be available on Chrome OS.
70	
71	  In order to work on non-Chrome OS platforms, we need to migrate it to an
72	  extension.  Unfortunately, doing so means we'd lose access to some APIs that
73	  we use on Chrome OS specifically.  The only option we're left with is to
74	  maintain both an extension and an app at the same time.
75	
76	  If you do not care about the Chrome OS specific features, then the two
77	  versions are equivalent.  Here are the few features available in the App:
78	
79	  * SFTP mounting
80	  * Access to [crosh](chromeos-crosh.md)
81	  * Icon shows up in the chrome://apps list (vs in the extension bar)
82	
83	  That is why we have a "Secure Shell App" and a "Secure Shell Extension" in
84	  the store (as well as "dev" versions of each).  You can safely have any of
85	  them installed simultaneously.
86	
87	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	88	### How do hterm and Secure Shell differ from existing web terminals?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	89	
90	  hterm stands out from many existing web terminals in that it was built from
91	  the start to match the performance and correctness of "native" terminals such
92	  as xterm and Terminal.app.
93	
94	  It can handle large bursts of text quickly, support very large scrollback
95	  buffers, and it closely matches xterm's behavior.  The keyboard even mostly
96	  works.  (ha!  See the note about how to get Ctrl-W below.)
97	
98	  The Secure Shell app is different because it does not require a proxy or
99	  relay server to function.  Secure Shell can make a direct connection to
100	  a standard sshd server on any port of the destination machine.  Other
101	  web terminals require a proxy server in the middle.  In some cases you
102	  are even required to hand the proxy your credentials in plain text.
103	
104	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	105	### What should I do if I notice a bug?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	106	
107	  First, please continue reading this FAQ to make sure your issue isn't
Mike Frysinger	a62bc04	2016-03-04 05:09:34	[diff] [blame]	108	  mentioned.  Then check the bug list at <https://goo.gl/VkasRC>.
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	109	
110	  If you don't see the issue there, you can search the archives of the
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	111	  [chromium-hterm mailing list].
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	112	
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	113	  If all else fails then join the [chromium-hterm mailing list] and post
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	114	  about what you've found.
115	
Mike Frysinger	f2e195f	2017-05-04 00:34:47	[diff] [blame]	116	  To file an actual report, you can use <https://goo.gl/vb94JY>.  This will
117	  route to the right people.
118	
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	119	  If your bug involves some mis-interpreted escape sequence and you want
120	  to file a really useful bug report, then add in a recording of the
121	  session.  For bonus points, track down the troublesome sequence and
122	  include the offset into the log file.  For more information about how to
Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	123	  do this, see the "Debugging escape sequences" section in the
Mike Frysinger	47cad27	2017-03-01 19:38:30	[diff] [blame]	124	  [hack.md](hack.md) file in this directory.
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	125	
126	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	127	### Is there a mailing list to discuss hterm or Secure Shell?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	128	
Mike Frysinger	71d42b6	2017-04-17 18:01:18	[diff] [blame]	129	  Yes, there is a public [chromium-hterm mailing list] anyone can join!
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	130	
131	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	132	### Is there a way to try early releases of Secure Shell?
133	
134	  Yes.  First, you need to subscribe to the [chromium-hterm mailing list].
Mike Frysinger	6266598	2017-12-17 06:26:39	[diff] [blame]	135	  Subscribers have access to the "Dev" versions in the Chrome Web Store, which
136	  are located here:
137	
138	  * [App for Chrome OS](https://goo.gl/cFZlv)
139	  * [Extension for all systems](https://goo.gl/9NCCZQ)
140	
141	  Note: You'll also need to sign in to the Chrome Web Store using the same
142	  account that joined the mailing list.  Otherwise, the link will result in a
143	  404 error.
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	144	
145	  Please keep in mind that the Dev version has gone through significantly less
Mike Frysinger	6266598	2017-12-17 06:26:39	[diff] [blame]	146	  testing than the stable versions.  Fortunately, you can install both and
147	  switch back to stable if you have trouble with Dev.
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	148	
149	
150	### Where is the source code?
151	
152	  The hterm source is here: <https://goo.gl/8qndhN>.  This includes the
153	  front-end code for Secure Shell.
154	
155	  The Native Client wrapper around ssh is here: <https://goo.gl/4tZCMI>.
156	
157	### Is there a changelog?
158	
159	  Yes.  Look under the doc/ directory for each project.
160	
161	  There is [one for hterm](../../hterm/doc/ChangeLog.md) and
162	  [one for Secure Shell](./ChangeLog.md).
163	
164	
165	### What if I want to make changes to the source?
166	
167	  Read the [hack.md](hack.md) file in this directory.
168	
169	
170	## Secure Shell (ssh) Questions
171	
172	
173	### Is my connection proxied in any way?
174	
175	  No.  By default all connections are made directly to the sshd server on the
176	  destination machine.
177	
178	
179	### But, what if I *want* to ssh over HTTP?
180	
181	  Secure Shell also knows how to connect to an HTTP-to-ssh relay that was
182	  built inside Google.  Unfortunately that relay isn't open source, and Google
183	  doesn't maintain a public pool of relays.
184	
185	  However, you're free to build one that works the same way.  There should be
186	  enough documentation in [nassh_google_relay.js](../js/nassh_google_relay.js)
187	  to reverse engineer a compatible relay.
188	
189	  The good news is that someone has built an
190	  [open source relay](https://github.com/zyclonite/nassh-relay).  It is not
191	  supported by us though, so please take any questions/concerns about it to
192	  the author.
193	
194	
195	### Is my connection really secure?
196	
197	  The Secure Shell app uses ssh to manage the encrypted communication channels.
198	  This makes it about as secure as any other connection based on the ssh
199	  command.
200	
201	  It does have the added advantage of running ssh as a sandboxed
202	  Native Client plugin, which in theory makes it more secure than an
203	  unsandboxed ssh connection.
204	
205	  Additionally, the Secure Shell application follows a strict Content Security
206	  Policy that does not allow access to the JavaScript 'eval' function.  This
207	  helps lower the risk that a terminal exploit could run arbitrary JavaScript.
208	
209	
210	### Can I connect using a public key pair or certificate?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	211	
212	  You can import identity files from the connection dialog.  Select the
213	  "Import..." link to bring up a file picker.
214	
215	  You must import two files for each identity.  One should be the private key
216	  and should not have a file extension.  The other should be the public key,
217	  and must end in ".pub".  For example, "id_rsa" and "id_rsa.pub".
218	
219	  If you have a key stored in a single ".pem" file, you must split it into two
220	  files before importing.
221	
222	  This will import your public/private key files into the HTML5 filesystem
223	  associated with Secure Shell.  There should be no way for another extension,
224	  app, or web page to access this sandboxed filesystem.
225	
Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	226	*** note
227	  Keep in mind that HTML5 filesystems are relatively new.  As always,
228	  it's possible that there are still exploits to be found or disclosed.
229	
Mitchell McDermott	a30693b	2016-11-29 05:39:07	[diff] [blame]	230	  Additionally, Chrome stores HTML5 filesystems as normal files (with mode
Mike Frysinger	6f8ef70	2016-02-14 07:31:08	[diff] [blame]	231	  600, "-rw-------") under your profile directory.  Non-Chrome
232	  applications on your system may be able to access these files.
233	
234	  For your own good, protect your important private keys with a strong
235	  passphrase.
236	***
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	237	
238	  You can also import a traditional ssh 'config' file using this dialog.
239	  Nearly anything that ssh might care about from your ~/.ssh directory can go
240	  here.
241	
Mike Frysinger	e453318	2017-04-19 04:18:29	[diff] [blame]	242	  See <http://man.openbsd.org/ssh_config> for more information about the ssh
243	  configuration syntax.  Keep in mind that any directives that would require
244	  access outside of the NaCl sandbox will not function properly.  This includes
245	  (but is not limited to) X11 forwarding,  syslog functionality, and anything
246	  that requires a domain socket.
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	247	
248	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	249	### Can I use my `~/.ssh/config` file?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	250	
251	  Probably.  It depends on what it does.  See the answer to the previous
252	  question for more details.
253	
254	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	255	### Is the SSH-1.x protocol supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	256	
257	  Not anymore.  The SSH-2.0 protocol has been available for over a decade.
258	  If you need this, then try contacting the [chromium-hterm mailing list].
259	  Your best bet though would be to upgrade the server, or find a different
260	  system/client to connect to the old system.
261	
262	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	263	### Is 1024-bit diffie-hellman-group1-sha1 key exchange supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	264	
265	  It is disabled by default at runtime.  You can enable it by adding
266	  `-oKexAlgorithms=+diffie-hellman-group1-sha1` to your ssh command line in the
267	  connection page.
268	
269	  However, these key types are insecure.  You should update your server to
270	  newer key types like RSA or ED25519.  Future support for these key types is
271	  not guaranteed.
272	
273	  See the [OpenSSH legacy options] page for more details.
274	
275	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	276	### Are ssh-dss and ssh-dss-cert-* keys supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	277	
278	  It is disabled by default at runtime.  You can enable it by adding
279	  `-oHostKeyAlgorithms=+ssh-dss` to your ssh command line in the connection
280	  page.
281	
282	  However, these key types are insecure.  You should update your server to
283	  newer key types like RSA or ED25519.  Future support for these key types is
284	  not guaranteed.
285	
286	  See the [OpenSSH legacy options] page for more details.
287	
288	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	289	### Are legacy v00 cert formats supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	290	
291	  Not anymore.  You'll need to use a different client to connect if those are
292	  the only ciphers your server supports.
293	
294	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	295	### Are blowfish-cbc, cast128-cbc, arcfour variants, the rijndael-cbc AES aliases, and 3des-cbc ciphers supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	296	
297	  Not anymore.  You'll need to use a different client to connect if those are
298	  the only ciphers your server supports.
299	
300	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	301	### Are RSA keys smaller than 1024 bits supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	302	
303	  Not anymore.  Keys smaller than 1024 bits are insecure.  You'll need to
304	  generate new keys and use those instead.
305	
306	  If you still need to connect to such a system, you'll have to use a different
307	  client to connect.
308	
309	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	310	### Are MD5-based HMAC algorithms supported?
Mike Frysinger	a8ccb76	2017-04-12 01:31:59	[diff] [blame]	311	
312	  Not anymore.  You'll need to use a different client to connect if those are
313	  the only ciphers your server supports.
314	
315	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	316	### How do I remove a key?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	317	
318	  From the connection dialog, select an identity from the dropdown and press
319	  the DELETE key.  This will remove both the private and public key files from
320	  the HTML5 filesystem.
321	
322	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	323	### How do I remove ALL keys?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	324	
325	  Open the JavaScript console and type...
326	
327	    term_.command.removeDirectory('/.ssh/')
328	
329	  This will remove any non-key files you may have uploaded as well.  It will
330	  *not* affect your preferences.
331	
332	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	333	### Is there support for keychains?
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	334	
335	  Sorry, not yet.  This is a bit of a technical challenge given the nature
336	  of the NaCl sandbox.  We have a few options that we're exploring.  Feel
Mike Frysinger	71d42b6	2017-04-17 18:01:18	[diff] [blame]	337	  free to post your ideas to the [chromium-hterm mailing list].
Robert Ginda	b4839c2	2013-03-01 00:52:10	[diff] [blame]	338	
339	  (And yes, we're already considering integrating with the Chrome NSS
340	  certificate store.)
341	
342	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	343	### Is IPv6 supported?
Mike Frysinger	c766247	2017-04-08 03:35:47	[diff] [blame]	344	
345	  Mostly.  You can connect to hostnames that resolve to IPv6 addresses, and
346	  you can connect directly IPv6 addresses.  Enter them in the connection
347	  manager like any other hostname or IPv4 address.
348	
349	  When using links (see the next section), you'll need to use the standard
350	  bracket style such as `[::1]`.
351	
352	  However, [zone ids](https://tools.ietf.org/html/rfc4007#section-11) are not
353	  yet supported.
354	
355	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	356	### Can I create bookmarks to specific sites?
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	357	
Mike Frysinger	b2ad22c	2017-03-29 08:07:35	[diff] [blame]	358	  Mostly.  You can create a few types of bookmarks:
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	359	  1. A connection specifying a user & host (and optionally a port).
360	  2. A profile connection (which you already created/set up).
Mike Frysinger	b2ad22c	2017-03-29 08:07:35	[diff] [blame]	361	  3. A `ssh://` URL.
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	362	
363	*** aside
Mike Frysinger	6266598	2017-12-17 06:26:39	[diff] [blame]	364	In the examples below, the *[ID]* field will need adjusting based on the
365	version you have installed:
366	
367	* `pnhechapfaindjhompbnflcldabbghjo`: Secure Shell App (stable)
368	* `okddffdblfhhnmhodogpojmfkjmhinfp`: Secure Shell App (dev)
369	* `iodihamcpbpeioajjeobimgagajmlibd`: Secure Shell Extension (stable)
370	* `algkcnfjnajfhgimadimbjhmpaeohhln`: Secure Shell Extension (dev)
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	371	***
372	
Mike Frysinger	bd7be8b	2017-04-21 19:20:57	[diff] [blame]	373	#### Direct links
Mike Frysinger	9889617	2016-06-03 20:13:16	[diff] [blame]	374	
375	  The first one takes the form of:
376	
Mike Frysinger	6266598	2017-12-17 06:26:39	[diff] [blame]	377	  `chrome-extension://[ID]/html/nassh.html#user@host[:port][@proxyhost[:proxyport]]`