From 503811b6a8cfd79d2ca6aef69488f8e8c185db31 Mon Sep 17 00:00:00 2001
From: Deepti Navale <dnavale@redhat.com>
Date: Wed, 27 Aug 2014 16:29:48 +1000
Subject: [PATCH] Included information about keyring support

Added info about keyring support to the user guide.
Closes-Bug: #1199007

Change-Id: Ie62f53bbf80cc11303cf03985854ebecf7cfa15f
---
 doc/common/section_cli_openrc.xml             |  1 +
 .../section_keystone-keyring-support.xml      | 28 +++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 doc/common/section_keystone-keyring-support.xml

diff --git a/doc/common/section_cli_openrc.xml b/doc/common/section_cli_openrc.xml
index 8da2c00308..99e98f4bfb 100644
--- a/doc/common/section_cli_openrc.xml
+++ b/doc/common/section_cli_openrc.xml
@@ -129,4 +129,5 @@ export OS_REGION_NAME=<replaceable>regionName</replaceable></programlisting>
         <screen><prompt>$</prompt> <userinput>keystone --os-password <replaceable>PASSWORD</replaceable> service-list</userinput></screen>
         <para>Where <replaceable>PASSWORD</replaceable> is your password.</para>
     </section>
+    <xi:include href="../common/section_keystone-keyring-support.xml"/>
 </section>
diff --git a/doc/common/section_keystone-keyring-support.xml b/doc/common/section_keystone-keyring-support.xml
new file mode 100644
index 0000000000..134e9ae765
--- /dev/null
+++ b/doc/common/section_keystone-keyring-support.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         version="5.0"
+         xml:id="section_keystone-keyring-support">
+  <title>Keyring support</title>
+  <para>Keyring is a password management system available in OpenStack.
+    You can install it using the following command:</para>
+  <screen><prompt>$</prompt> <userinput>pip install keyring</userinput></screen>
+  <note>
+    <para>Keyring is used only if <parameter>--os-use-keyring</parameter>
+      is specified or if the environment variable
+      <parameter>OS_USE_KEYRING=true</parameter> is defined.</para>
+  </note>
+  <para>A user specifies their username and password credentials to interact
+    with OpenStack, using any client command. These credentials can be specified
+    using various mechanisms, namely, the environment variable, or command line argument.
+    It is not safe to specify the password using either of these methods.</para>
+  <para>For example, when you specify your password using the command-line client
+    with the <parameter>--os-password</parameter> argument, anyone with access
+    to your computer can view it in plain text with the <parameter>ps</parameter>
+    field.</para>
+  <para>To avoid storing the password in plain text, you can prompt for the
+    OpenStack password interactively. Then, the keyring can store the password
+    and the user can safely retrieve it from their keyring. The encrypted password
+    is stored in the <filename>~/.openstack-keyring.cfg</filename> file.</para>
+</section>