[seahorse/wip/userdocs: 29/229] help: key-subkeys.page

[Ekaterina Gerasimova <egerasimov src gnome org>]

commit 68144ce071012fc6ec51324288d3f07d86e7b504
Author: Aruna Sankaranarayanan <arunasank src gnome org>
Date:   Fri Jun 28 15:46:24 2013 +0530

    help: key-subkeys.page

 help/C/key-subkeys.page |  124 ++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 111 insertions(+), 13 deletions(-)
---
diff --git a/help/C/key-subkeys.page b/help/C/key-subkeys.page
index fb74810..3bab67d 100644
--- a/help/C/key-subkeys.page
+++ b/help/C/key-subkeys.page
@@ -3,11 +3,14 @@
       id="key-subkeys">
   <info>
     <link type="guide" xref="learn-about-keys" group="second"/>
+
     <revision version="0.1" date="2011-10-23" status="stub"/>
-    <credit type="author">
-      <name>Jim Campbell</name>
-      <email>jwcampbell gmail com</email>
-      <years>2011</years>
+    <revision pkgversion="3.9" version="0.1" date="2013-06-28" status="draft"/>
+
+    <credit type="author copyright">
+      <name>Aruna Sankaranarayanan</name>
+      <email>aruna evam gmail com</email>
+      <years>2013</years>
     </credit>
 
     <desc></desc>
@@ -15,18 +18,113 @@
 
   <title>What are subkeys?</title>
 
-  <comment>
-    <cite date="2011-10-23" href="mailto:jwcampbell gmail com">Jim Campbell</cite>
-    <p>This assumes the reader knows how to.... By the end of this page,
-    the reader will be able to....</p>
-  </comment>
+  <p>Though it is very important to keep your keys safe, it can become quite
+  tedious to do so when you have many keys. <app>Passwords and Keys</app>
+  provides a simple solution to key safety by using special keys called
+  <em>subkeys</em> for signing and encryption.</p>
+
+  <p>Whenever you create a new public encryption key, a <em>key pair</em> is
+  generated instead of a single key. This keypair consists of a main key, also
+  called the <em>master key</em>, which can only sign, and a <em>subkey</em>
+  for encryption and decryption. Additional subkeys can be created for signing.
+  Each subkey is bound to the master key that created it.</p>
+
+  <list>
+    <title>What does each key in a keypair do?</title>
+      <item>
+       <p>The <em>master key</em> is used for
+       <link xref="key-signing">signing</link> other keys, creating subkeys
+       and <link xref="key-disabling">revoking</link> subkeys. Your master key
+       must be kept very safe.  If the master key is compromised, you have no
+       choice but to revoke it and all the subkeys attached to it.</p>
+      </item>
+      <item>
+       <p>The default <em>subkey</em> is used for encryption and decryption
+       of messages. Additional subkeys can be created for signing. Though it
+       is important that your subkeys are kept safe, you can always revoke a
+       subkey if it is compromised and create a new one with the original
+       master key.</p>
+      </item>
+  </list>
 
-  <p>Short introductory text...</p>
+<section id ="check">
+  <title>Examine your keypair</title>
+
+  <p>You can check the contents of a keypair to see the properties of a
+  subkey.</p>
 
   <steps>
-    <item><p>First step...</p></item>
-    <item><p>Second step...</p></item>
-    <item><p>Third step...</p></item>
+    <title>To see all the <em>subkeys</em> in a keypair:</title>
+      <item>
+       <p>Select the <em>GnuPG keypair</em> of your choice from the list.</p>
+      </item>
+      <item>
+       <p>Right click on the key chosen in the previous step and select
+       <guiseq><gui>Properties</gui><gui>Details</gui></guiseq>.</p>
+      </item>
+      <item>
+       <p>If the <gui>Subkeys</gui> section is not expanded, expand
+       it.</p>
+      </item>
+      <item>
+       <p>Out of the two keys listed, the first one is your master key and
+       all the other keys that follow it are your subkeys.</p>
+       <note style="bug">
+         <p>This is a bug. When you create a new public cryptography key and
+         check the <gui>Subkeys</gui> section, you will see two subkeys listed
+         even though only one is created by default.  This is because
+         <app>Passwords and Keys</app> lists all the keys in the keypair in
+         the <gui>Subkeys</gui> section instead of listing only the subkeys.
+         So, the master key is also listed under <gui>Subkeys</gui> even
+         though it is not one.</p>
+       </note>
+      </item>
   </steps>
 
+  <note style="info">
+    <p><app>Passwords and Keys</app> stores your keypairs under
+    <gui>GnnuPG Keys</gui> if you have enabled the
+    <guiseq><gui style="menu">View</gui>
+    <gui style="menuitem">By Keyring</gui></guiseq> option. While signing, you
+    only need to select the keypair, <app>Passwords and Keys</app>
+    automatically chooses the master key for signing.</p>
+ </note>
+
+</section>
+
+<section id="add">
+  <title>Add extra <em>subkeys</em></title>
+
+  <p>You can have additional subkeys for the same master key. You have to
+  choose the right subkey each time you want to encrypt or sign when you do
+  this.</p>
+
+  <steps>
+    <title>To add extra subkeys:</title>
+      <item>
+        <p>Select the <em>GnuPG keypair</em> of your choice from the list.</p>
+      </item>
+      <item>
+       <p>Right click on the key chosen in the previous step and select
+       <guiseq><gui>Properties</gui><gui>Details</gui></guiseq>.</p>
+      </item>
+      <item>
+        <p>If the <gui>Subkeys</gui> section is not expanded, expand it.</p>
+      </item>
+      <item>
+       <p>Click the <gui style="button">Add</gui>button to add a new subkey.</p>
+      </item>
+      <item>
+       <p>Choose the right properties for your key by selecting the
+       appropriate <gui>Key Type</gui>, <gui>Key Length</gui> and
+       <gui>Expiration Date</gui> and click <gui style="button">OK</gui>.</p>
+       <note style="info">
+         <p>Always ensure that your subkey does not expire after your master
+         key since a subkey is useless when its master key has expired.</p>
+       </note>
+      </item>
+  </steps>
+
+</section>
+
 </page>