added a recipe for ssh keys

1 files changed, 133 insertions, 0 deletions

diff --git a/en-US/Security/ssh-keygen.xml b/en-US/Security/ssh-keygen.xml
new file mode 100644
index 0000000..4435c0a
--- /dev/null
+++ b/en-US/Security/ssh-keygen.xml
@@ -0,0 +1,133 @@
+<?xml version='1.0' encoding='utf-8' ?>
+ <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+  <!ENTITY % BOOK_ENTITIES SYSTEM "../Fedora_Cookbook.ent">
+    %BOOK_ENTITIES;
+]>
+<!-- Do not edit above this line -->
+<!-- 
+     Please provide some information so we can give you credit:
+     name: Pete Travis
+     fas_id: immanetize
+     email: immanetize@fedoraproject.org
+-->
+
+<section id="ssh-keygen">
+  <title>Creating SSH Keys</title>
+  <para>
+    Secure Shell, or SSH, is a powerful and popular tool for connecting to Fedora systems over local or global networks.  SSH is more secure when used with <literal>keys</literal>.  Like a physical key and lock, an ssh public and private key are paired to work only with each other.  Using keys can make connecting easier, and systems that use keys can be made more secure by turning off ssh password access.
+  </para>
+  <section id="ssh-keygen-ingredients">
+    <title>Required Ingredients</title>
+    <!-- list packages, services, other recipes etc that are required -->
+    <itemizedlist>
+      <listitem><para>
+          <package>openssh-clients</package> - Package, comes by default on most systems.
+      </para></listitem>
+      <listitem><para>
+          <package>openssh</package> - Package, comes by default on most systems.
+      </para></listitem>
+      <listitem><para>
+          <emphasis>Working Network Connection</emphasis> - Network services need a network!
+      </para></listitem>
+      <listitem><para>
+          <emphasis>Target host</emphasis> - Another computer that you have network and password access to. You will need either an IP address or a domain name for this machine.
+      </para></listitem>
+    </itemizedlist>
+    <note>
+      <title>Local testing</title>
+      <para>
+        To test ssh access against the local machine instead of another on the network, use <systemitem class="domainname">localhost</systemitem> as the target hostname.
+      </para>
+    </note>
+      
+      </section>
+  <section id="ssh-keygen-directions">
+  <title>Directions</title>
+    <procedure>
+      <title>Setting up SSH Keys</title>
+      <step><para>
+          Create the key.
+          <screen>
+            <command>ssh-keygen -b 4096 -N "<replaceable>secret</replaceable>" -f <filename class="directory">~/.ssh/<replaceable>target_id_isa</replaceable></filename></command>
+          </screen>
+        </para>
+        <para>
+          If you don't declare any options, <application>ssh-keygen</application> will ask for the required minimum interactively. Read about the example's options below, or find more options in <command>man ssh-keygen</command>.
+          <simplelist>
+            <member>
+              <parameter>-b 4096</parameter> : Generates a 4096-bit key, stronger than the default.
+            </member>
+            <member>
+              <parameter>-n <replaceable>secret</replaceable></parameter> : A passphrase for the key. Optional, but strongly recommended.
+            </member>
+            <member>
+              <parameter>-f <filename class="directory">~/.ssh/<replaceable>target_id_rsa</replaceable></filename></parameter> : The file to create. Call the file anything, but store it in <filename class="directory">~/.ssh/</filename>
+            </member>
+          </simplelist>
+      </para></step>
+      <step>
+        <para>
+          Copy the public key to your target. 
+          <screen>
+            <command>
+              ssh-copy-id -i ~/.ssh/<replaceable>target_id_rsa</replaceable>.pub <replaceable>target_ip</replaceable>
+            </command>
+          </screen>
+        </para>
+        <para>
+          The <application>ssh-copy-id</application> utility opens an ssh connection to the target using password authentication and adds the contents of the public key to <filename>~/.ssh/authorized_keys</filename>`. The file can also be shared by other means and appended to <filename>authorized_keys</filename> manually, a method used for systems where password authentication cannot be turned on.
+          <screen>
+            <command>cat target_id_rsa.pub >> ~/.ssh/authorized_keys</command>
+          </screen>
+        </para>
+      </step>
+      <step>
+        <para>
+          Test the key:
+          <screen>
+            <command>
+              ssh -i ~/.ssh/target_id_rsa -o PasswordAuthentication=no <replaceable>target_ip</replaceable>
+            </command>
+          </screen>
+        </para>
+      </step>
+      <step><para>
+          Add an entry in your client ssh configuration for the key. <application>ssh</application> will try all keys in <filename>~/.ssh/</filename> when connecting to any host unless configured otherwise, so configuring it to only use keys that are explicitly paired to a host will reduce rejected authentication attempts and speed connections.
+        </para>
+        <formalpara>
+          <title>Editing <filename>~/.ssh/config</filename></title>
+            <para>
+          <screen>
+            Host *
+              IdentitiesOnly yes
+
+            Host <replaceable>target_ip</replaceable>
+              PasswordAuthentication No
+              IdentityFile ~/.ssh/<replaceable>target_id_rsa</replaceable>
+            </screen>
+          </para>
+      </formalpara></step>
+    </procedure>
+  </section>
+
+  <section>
+    <title>References</title>
+    <itemizedlist>
+      <listitem>
+        <para><citetitle>ssh-keygen(1)</citetitle> - manual for ssh-keygen</para>
+      </listitem>
+      <listitem>
+        <para>
+          <citetitle>ssh-copy-id(1)</citetitle> - manual for ssh-copy-id
+        </para>
+      </listitem>
+      <listitem>
+        <para><citetitle>ssh-config(5)</citetitle> - manual for ssh client configuration files</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+</section>
+
+