doc/tutorial.sgml

   1 <!DOCTYPE article  PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
   2  [ <!ENTITY % output.print.png "IGNORE">
   3 <!ENTITY % output.print.pdf "IGNORE">
   4 <!ENTITY % output.print.eps "IGNORE">
   5 <!ENTITY % output.print.bmp "IGNORE">
   6  ]>
   7
   8 <!-- SGML file was created by LyX 2.0.3
   9   See http://www.lyx.org/ for more information -->
  10 <article lang="en">
  11 <articleinfo>
  12 <title>Libpwmd Tutorial</title>
  13 <date>6-2-2012</date><author>
  14 Ben Kibbey<footnote><dummy>bjk@luxsci.net</dummy></footnote><toc></toc></author></articleinfo><sect1>
  15 <title>Introduction</title>
  16 <para>This is a tutorial showing the basic usage of libpwmd<footnote><dummy>http://libpwmd.sourceforge.net/</dummy></footnote>. Libpwmd<emphasis> </emphasis>is a library making it easy for applications to use pwmd<footnote><dummy>http://pwmd.sourceforge.net/</dummy></footnote> (<emphasis>Password Manager Daemon). Password Manager Daemon</emphasis> is a universal data server. It began as a way to keep track of my passwords for accounts like email and websites but can be used to store anything you want.</para>
  17 <para>There are other password management tools but pwmd has a couple of distinguishing features:</para><itemizedlist>
  18 <listitem><para>It does not depend on a desktop environment but has the ability for applications to connect to it like a desktop solution provides.</para></listitem><listitem><para>Some portion of a stored data can be shared with another portion in the same data file. This feature behaves a lot like a symbolic link on a file system, XML entities, or HTML targets if you're familiar with those, but implemented in a different way. This means less duplication of content. See <xref linkend="sec:Linking-elements"> for details.</para></listitem><listitem><para>The document is encrypted with GnuPG and uses gpg-agent for passphrase handling. GnuPG supports both symmetric and PKI encryption and smartcards are also supported.</para></listitem></itemizedlist><para>Other features include:</para><itemizedlist>
  19 <listitem><para>Multi-threaded. More than one client may access the same data file while optionally locking out other clients.</para></listitem><listitem><para>Secure memory management. Pwmd will zero out memory before freeing it and the contents of the cached document are encrypted.</para></listitem><listitem><para>Remote connections over TLS with client certificates used as authentication.</para></listitem></itemizedlist></sect1><sect1>
  20 <title>File Format and Element Paths</title>
  21 <para>The document is saved as an XML document and is manipulated by commands sent from a client. Commands that access data take what is called an <emphasis>element path</emphasis> as an argument. An element path is a character string containing XML element names representing branches of an element tree. The branches are separated with a TAB (ASCII 0x09) character. Why a TAB? So other characters can be used in the element name. If for example a '/' were used as the separator, then a URL (i.e., http://sf.net/) could not be used as an element name.</para>
  22 <para>For the rest of this tutorial, when you see &lt;TAB&gt;, replace it with a real TAB character. For example, the element path "a&lt;TAB&gt;child&lt;TAB&gt;last" has the following element tree:</para><screen>
  23 <![CDATA[<root>
  24     <child>
  25         <last>
  26 Content or XML CDATA of the "last" element.
  27         </last>
  28     </child>
  29 </root>
  30 ]]></screen><para>I should say that the XML structure that pwmd uses is a little more complicated. It really looks like the following internally, but we will use the above format in this tutorial for simplicity:</para><screen>
  31 <![CDATA[<element _name="root">
  32     <element _name="child">
  33         <element _name="last">
  34 Content or CDATA of the "last" element.
  35         </element>
  36     </element>
  37 </element>
  38 ]]></screen><para>Every element created has an element named <emphasis>element</emphasis> with an attribute <emphasis>_name</emphasis> associated with it. The value of the <emphasis>_name</emphasis> attribute is what an element in an element path refers to. It is done this way so that a wider range of characters can be used in an element name while maintaining valid XML. In fact, the only restriction of an element name is that it not contain whitespace characters and not begin with an exclamation point (ASCII 0x21 or !). See <emphasis><xref linkend="sec:Linking-elements"> </emphasis>for an exception.</para>
  39 <para>There is one other difference from your normal XML document in that only the first match of an element is considered for the current element tree depth. When an element of the current depth of an element tree is found, the next element in the element path is searched for beginning at the child node of the found element. From the example above:</para><screen>
  40 <![CDATA[<root>
  41     <child>
  42         <last>
  43 Content or XML CDATA of the "last" element.
  44         </last>
  45     </child>
  46     <child>
  47 This element will never be reached.
  48     </child>
  49 </root>
  50 ]]></screen><para>The second "child" element is never reached.</para></sect1><sect1>
  51 <title>Connecting to PWMD</title>
  52 <para>You will need a <emphasis>pwmd</emphasis> client to send commands to the pwmd server. <emphasis>libpwmd</emphasis> includes a client named <emphasis>pwmc</emphasis>. It is command-line based and there are not any fancy graphics, but it is good for understanding how <emphasis>pwmd</emphasis> commands are processed. If you want a more user friendly client that resembles a file manager and has a point and click interface, try qpwmc <footnote><dummy>http://qpwmc.sourceforge.net/</dummy></footnote> which uses the Qt4 toolkit and is also a full featured client.</para>
  53 <para>In this tutorial we will use the <emphasis>pwmc</emphasis> client included with libpwmd. <emphasis>pwmc</emphasis> has two modes that commands are read from: interactive and stdin. The interactive mode uses the readline library and has command history while reading from standard input (stdin) makes shell scripting and automation easy. For the examples, we will be connecting to the default local unix domain socket that pwmd waits for connections on. Remote connections are possible over TLS or an SSH channel but those are not covered here. Read the pwmc(1) manual page for details about how to do that.</para>
  54 <para>The example filename we will use is "datafile". It is initially a non-existent file but it will be created once we have saved to it. Now let us connect to the server in interactive mode and open the data file:</para><screen>
  55 <![CDATA[$ pwmc datafile
  56 Connected.
  57 pwm>
  58 ]]></screen><para>The "pwm&gt;" prompt is a readline prompt that has command history and can do filename completion. It also is annoying because, as mentioned, elements in element paths are TAB delimited, but command completion in readline uses the TAB character, too. To insert a real TAB character in interactive mode rather than do readline completion, you will need to first press CTRL-V and then press TAB.</para></sect1><sect1>
  59 <title>Commands</title>
  60 <para>There are two different types of commands: client commands and protocol commands. The client commands are <emphasis>pwmc</emphasis> specific and only available to the <emphasis>pwmc</emphasis> client. Protocol commands are commands sent from any client and to the <emphasis>pwmd</emphasis> server. All pwmc client commands are prefixed with a period '.' followed by the command name. Protocol commands are sent without any prefix. To see the available pwmc and protocol commands, send the HELP command:</para><screen>
  61 <![CDATA[pwm> .help
  62 ]]></screen><para>or</para><screen>
  63 <![CDATA[pwm> help
  64 ]]></screen><para>To store some data in an element path, you will need to know what element path to create. It is up to you how you want your data organized. If for example you will be storing account information it may be good to categorize what the account is for: email, instant messaging, blogging, etc. An application that uses libpwmd may require that a certain element path exists. Refer to that applications documentation to determine what element paths need to be created.</para>
  65 <para>In the following example we will setup mail server element paths which can be used for other applications requiring a mail server configuration. First, lets create the hostname element path:</para><screen>
  66 <![CDATA[pwm> STORE
  67 ]]></screen><para>The STORE command is a <emphasis>pwmd</emphasis> protocol command. This command, and some other commands, use what is called a <emphasis>server inquire</emphasis> to retrieve data from the client while other commands may retrieve the data only from the command arguments. The server inquire will wait for the client to finish sending its data before completing the command. When responding to a server inquire in pwmc, pwmc will show a message telling you that it is waiting for data to be sent. Enter the element path and its content, then press &lt;CTRL-D&gt; twice to finish sending the data and to let <emphasis>pwmd</emphasis> complete the command:</para><screen>
  68 <![CDATA[pwm> STORE
  69 email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
  70 ]]></screen><para>Remember that you should replace &lt;TAB&gt; in the examples with a real TAB character. I should mention that when sending data via a server inquire there is no need to press &lt;CTRL-V&gt; to insert the &lt;TAB&gt; character. That is only needed from the readline command prompt and when not doing a server inquire.</para>
  71 <para>After pressing the first &lt;CTRL-D&gt;, the line that was entered is sent to <emphasis>pwmd</emphasis> and the inquire continues. To terminate the inquire and finish sending data for the command, press &lt;CTRL-D&gt; a second time.</para>
  72 <para>If you were to have pressed &lt;RETURN&gt; before any &lt;CTRL-D&gt; then the inquired line would have been sent in full including a newline character. Since in this example a newline character in a hostname is not a valid hostname, this is not what we want.</para>
  73 <para>We have just created an element path whose XML structure looks like the following:</para><screen>
  74 <![CDATA[<email>
  75     <isp>
  76         <IMAP>
  77             <hostname>imap.server.com</hostname>
  78         </IMAP>
  79     </isp>
  80 </email>
  81 ]]></screen><para>The GET protocol command returns the value of the last element of an element path. To retrieve the hostname of the element path we just created, do:</para><screen>
  82 <![CDATA[pwm> GET email<TAB>isp<TAB>IMAP<TAB>hostname
  83 imap.server.com
  84 ]]></screen><para>Remember that in interactive mode and when not doing a server inquire, you will need to press &lt;CTRL-V&gt; before pressing &lt;TAB&gt;.</para>
  85 <para>Let us create the rest of the needed elements:</para><screen>
  86 <![CDATA[pwm> STORE
  87 email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
  88 pwm> STORE
  89 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
  90 pwm> STORE
  91 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
  92 pwm> STORE
  93 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
  94 ]]></screen><para>Now the element structure for the "email" element looks like this:</para><screen>
  95 <![CDATA[<email>
  96     <isp>
  97         <IMAP>
  98               <hostname>imap.server.com</hostname>
  99               <port>993</port>
 100               <ssl>1</ssl>
 101         </IMAP>
 102         <username>myusername</username>
 103         <password>mypassword</password>
 104     </isp>
 105 </email>
 106 ]]></screen><para>If you wanted to change your password (after changing it on the mail server, of course) just do as you did when initially creating the password element path. The new content will overwrite the existing content:</para><screen>
 107 <![CDATA[pwm> STORE
 108 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
 109 ]]></screen><para>An application using libpwmd that needs to know mail server information now has all the information it needs. The only thing left to do now is to save the changes:</para><screen>
 110 <![CDATA[pwm> <CTRL-D>
 111 ]]></screen><para>After pressing &lt;CTRL-D&gt; a prompt will be shown asking what to do. Press &ldquo;s&rdquo; to save what we have created.</para>
 112 <para>Since this is a new file, you will be prompted for a passphrase to use for encryption. Once done, the data file is encrypted and written to disk and the passphrase is cached in pwmd so you do not need to enter it the next time your data file is opened or saved. There are a few pwmd configuration parameters that affect how this operates. See the <emphasis>pwmd</emphasis> documentation for details.</para></sect1><sect1 id='sec:Linking-elements' >
 113 <title><!-- anchor id="sec:Linking-elements" -->Linking elements</title>
 114 <para>One distinguishing feature of pwmd is the ability to share data of one element path with another. If for example your ISP lets you host a blog on their server and you use a blogging client that can use libpwmd for authentication details, you can share authentication information with the email example above when the account details are the same. When element linking is used, this avoids the need to change the content for both the blogging and email password elements.</para>
 115 <para>This is done by setting a special &ldquo;target&rdquo; attribute for an element. It behaves similarly to the HTML &ldquo;target&rdquo; attribute or XML entities or a symbolic link on a filesystem. </para>
 116 <para>Let's create an example blogging element path:</para><screen>
 117 <![CDATA[pwm> STORE
 118 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
 119
 120 pwm> ATTR SET target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
 121 pwm> ATTR SET target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
 122 ]]></screen><para>Now each access of the "blog/isp/username" and "blog/isp/password" element paths, which were created if they did not already exist, will point to "email/isp/username" and "email/isp/password" respectively. To retrieve the value or content of an element that contains a "target" attribute without following any &ldquo;target&rdquo; attribute, prefix the element with a '!' when specifying it in an element path. For example:</para><screen>
 123 <![CDATA[pwm> GET blog<TAB>isp<TAB>!password
 124 ERR 536870938: No value
 125 ]]></screen><para>An error is returned because we have not assigned a value to the literal element. A literal element is an element that either contains no "target" attribute or ignores it by prefixing the element with the mentioned literal element character '!'. Let us try storing an example password to the literal element to show usage:</para><screen>
 126 <![CDATA[pwmd> STORE
 127 blog<TAB>isp<TAB>!password<TAB>literalpassword<CTRL-D><CTRL-D>
 128 ]]></screen><para>Now when we redo the previous GET command:</para><screen>
 129 <![CDATA[pwm> GET blog<TAB>isp<TAB>!password
 130 literalpassword
 131 ]]></screen><para>This is the value of the literal password element of the element path. To follow the element path stored in the "target" attribute, omit the '!' in the password element. This will return the &ldquo;email/isp/password&rdquo; element content:</para><screen>
 132 <![CDATA[pwm> GET blog<TAB>isp<TAB>password
 133 mypassword
 134 ]]></screen><para>A "target" attribute may also refer to another element with a "target" attribute. Every "target" attribute will be followed until there are no others to resolve. To get the real element path and resolve all "target" attributes, use the REALPATH command:</para><screen>
 135 <![CDATA[pwm> REALPATH blog<TAB>isp<TAB>password
 136 !email<TAB>!isp<TAB>!password
 137 ]]></screen><para>As you can see each element is prefixed with the literal '!' character meaning that no "target" attribute exists in any element of the resulting element path.</para>
 138 <para>Using the LIST command is useful to show the element structure of a document:</para><screen>
 139 <![CDATA[pwm> LIST
 140 !email
 141 !blog
 142 pwm> LIST !email
 143 !email
 144 !email<TAB>!isp
 145 !email<TAB>!isp<TAB>!username
 146 !email<TAB>!isp<TAB>!password
 147 !email<TAB>!isp<TAB>!IMAP<TAB>!hostname
 148 !email<TAB>!isp<TAB>!IMAP<TAB>!port
 149 !email<TAB>!isp<TAB>!IMAP<TAB>!ssl
 150 pwm> LIST !blog
 151 !blog
 152 !blog<TAB>!isp
 153 !blog<TAB>!isp<TAB>!username
 154 !blog<TAB>!isp<TAB>username
 155 !blog<TAB>!isp<TAB>!password
 156 !blog<TAB>!isp<TAB>password
 157 ]]></screen><para>Notice that there are two username and password elements in the &ldquo;blog&rdquo; element path: each with and without the literal element character prefix. This shows that both the username and password elements contain a "target" attribute.</para>
 158 <para>For the final example, we will remove the &ldquo;target&rdquo; attribute of the blogging password element:</para><screen>
 159 <![CDATA[pwm> ATTR DELETE target blog<TAB>isp<TAB>!password
 160 ]]></screen><para>If we were to have omitted the '!' from the password element then pwmd would try to remove the "target" attribute from the "email/isp/password" element path. That would return an error because no &ldquo;target&rdquo; attribute had been set for that element.</para>
 161 <para>Note that the "blog" and "isp" elements have no literal element character prepended to them in the example. It is not needed because they have no &ldquo;target&rdquo; attribute themselves.</para>
 162 <para>Using &ldquo;target&rdquo; attributes can be confusing. The best way to get the hang of linking elements is to experiment and use the LIST and DUMP commands to show the document structure. Remember to use the literal element prefix '!' when you do not want to follow any "target" attributes.</para></sect1></article>