<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      xmlns:ui = "http://projectmallard.org/ui/1.0/"
      type="topic" style="task"
      id="ssh-create">

  <info>
    <link type="guide" xref="index#ssh-keys" group="first"/>

    <revision pkgversion="3.14" date="2014-10-06" status="incomplete"/>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <credit type="author">
      <name>Jim Campbell</name>
      <email its:translate="no">jwcampbell@gmail.com</email>
      <years>2013</years>
    </credit>
    <credit type="author">
      <name>Hashem Nasarat</name>
      <email its:translate="no">hashem@riseup.net</email>
      <years>2014</years>
    </credit>
    <credit type="copyright editor">
      <name>Ekaterina Gerasimova</name>
      <email its:translate="no">kittykat3756@gmail.com</email>
      <years>2014</years>
    </credit>

    <desc>Create SSH keys to log in to other computers.</desc>
  </info>

  <title>Create a new SSH key</title>

  <p>An SSH key will help you to create a secure connection between computers.
  Creating an SSH key creates both a <em>Public</em> and a <em>Private</em>
  key. Here is how to create a new key:</p>

    <steps>
      <item><p>Select <guiseq><gui>File</gui><gui>New…</gui></guiseq>.</p></item>
      <item><p>Select <gui>Secure Shell Key</gui> and then click
      <gui>Continue</gui>.</p></item>
      <item><p>Enter a description for the key. The key description will help
      you to identify the key later. For example, you could enter the date for
      the day, something about how the key will be used, or the server name on
      which you intend to install the key. The description field is optional,
      and how you describe the key is entirely up to you.</p></item>
      <item><p>You can change default settings for encryption type or key
      strength by expanding the <gui>Advanced key options</gui> panel.</p></item>
    </steps>

  <p>At this point, you can just create your key, or create your key
  and install it on a remote computer to enable password-free login.</p>

  <section id="ssh-just-create-key" ui:expanded="false">
    <title>Create your key and do not set up remote login</title>
    <p>You can create the SSH key, and choose to set it up later.</p>

    <steps>
      <item>
	<p>Press the <gui style="button">Just Create Key</gui> button.</p>
      </item>
      <item>
	<p>Type a passphrase for your SSH key and press
	<gui style="button">OK</gui>.</p>
      </item>
      <item>
	<p>Retype the passphrase and press <gui style="button">OK</gui> to
	finish.</p>
      </item>
    </steps>

    <p>The SSH key will now be listed in the <gui>OpenSSH keys</gui>
    keyring.</p>

    <note style="tip">
      <p> When you try to use your SSH key, your operating system will prompt
      you for the passphrase used during creation. This ensures that if someone
      gets access to your SSH key, they can't use it without the
      passphrase.</p>
    </note>

  </section>

  <section id="ssh-create-key-and-set-up" ui:expanded="false">
    <title>Create your key and install it on a remote computer</title>
    <p>One of the most useful things about having an SSH key is that you can
    install the public key on a remote computer. Doing this allows you to log
    in to a remote computer with SSH without needing to enter your password
    every time.</p>

    <steps>
      <item>
	<p>Press the <gui style="button">Create and Set Up</gui> button, and
	follow the above instructions on entering a passphrase.</p>
      </item>
      <item>
	<p>In the dialog window that opens, enter the <gui>Server address</gui>
	that you normally use to log in to the remote computer via SSH.</p>
      </item>
      <item>
	<p>Ensure that the <gui>Login name</gui> you use on the remote
	computer is correct, and press <gui>Set Up</gui>.</p>
      </item>
      <item>
	<p>The program will now attempt to connect to the specified
	<gui>Server address</gui> with the entered <gui>Login Name</gui>. If
	there are any problems in accessing the remote computer, a pop-up
	window will appear that explains the problem, and you can try again.
	Make sure that you have a network connection and that the remote
	computer is on and accessible.</p>
      </item>
      <item>
	<p>If connection to the remote computer was successful, a dialog box
	will appear which asks for the <gui>Password</gui> you use to log in to
	the remote computer. Enter your password, then press
	<gui style="button">OK</gui>.</p>
      </item>
    </steps>

    <p>The public part of the selected SSH key will now be installed on the
    remote computer and configured to allow password-free SSH login. You should
    now be able to log in to the remote computer via SSH without a
    password.</p>

    <note style="tip">
      <p>If SSH key authentication fails and you cannot use password
      authentication, contact the service administrator for further help.</p>
    </note>
  </section>
</page>
