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.0rc3
   9   See http://www.lyx.org/ for more information -->
  10 <article lang="en">
  11 <articleinfo>
  12 <title>Libpwmd Tutorial</title>
  13 <date>5-8-2011</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 to access pwmd<footnote><dummy>http://pwmd.sourceforge.net/</dummy></footnote> or <emphasis>Password Manager Daemon</emphasis>.</para></sect1><sect1>
  17 <title>What is PWMD?</title>
  18 <para><emphasis>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>
  19 <para>There are other password management tools but pwmd has a couple of distinguishing features:</para><itemizedlist>
  20 <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.</para></listitem></itemizedlist></sect1><sect1>
  21 <title>Element paths</title>
  22 <para>The document is saved as an XML file 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>
  23 <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>
  24 <![CDATA[<a>
  25     <child>
  26         <last>
  27 Content or XML CDATA of the "last" element.
  28         </last>
  29     </child>
  30 </a>
  31 ]]></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>
  32 <![CDATA[<element _name="a">
  33     <element _name="child">
  34         <element _name="last">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-1"> </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[<a>
  41     <child>
  42         <last>Content or XML CDATA of the "last" element.
  43         </last>
  44     </child>
  45     <child>This element will never be reached.
  46     </child>
  47 </a>
  48 ]]></screen><para>The second "child" element is never reached, although an element of a different name may be accessed.</para></sect1><sect1>
  49 <title>Clients</title>
  50 <para>You will need a client to send commands to the pwmd server. If you are making your own application or need a simple client to connect to the server then <emphasis>libpwmd</emphasis> may be used. It has few dependencies and - as mentioned - includes a client named <emphasis>pwmc</emphasis>. The rest of this tutorial will use pwmc. It is command-line based and there are not any fancy graphics, but it is good for understanding how commands are processed.</para>
  51 <para>If you want a more user friendly client that looks like a file manager and has a point and click interface, try pwmdEdit<footnote><dummy>http://qpwmc.sourceforge.net/</dummy></footnote> which uses the Qt4 toolkit.</para></sect1><sect1>
  52 <title>Connecting</title>
  53 <para>We are using the <emphasis>pwmc</emphasis> client included in libpwmd. pwmc 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 an SSH channel but that is not covered here. Read the pwmc(1) manual page for 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 --interactive 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>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 a good idea to categorize what the account is for: email, instant messaging, blogging, etc.</para>
  61 <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>
  62 <![CDATA[pwm> STORE
  63 ]]></screen><para>The STORE command is a pwmd 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 required 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 let pwmd complete the command:</para><screen>
  64 <![CDATA[pwm> STORE
  65 email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
  66 ]]></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 CTRL-V to insert the TAB character. That is only needed from the readline command prompt and when not doing a server inquire.</para>
  67 <para>After pressing the first CTRL-D, the line that was entered is sent to pwmd and the inquire continues. To terminate the inquire and finish sending data for the command, press CTRL-D a second time.</para>
  68 <para>If you were to have pressed RETURN before any CTRL-D 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>
  69 <para>We have just created an element path whose XML structure looks like the following:</para><screen>
  70 <![CDATA[<email>
  71     <isp>
  72         <IMAP>
  73             <hostname>imap.server.com</hostname>
  74         </IMAP>
  75     </isp>
  76 </email>
  77 ]]></screen><para>When an application needs to retrieve the content for the element path we have just created, it will send the GET command (libpwmd does this part) to the pwmd server. You can retrieve the content of an element path by using the GET command in pwmc, too:</para><screen>
  78 <![CDATA[pwm> GET email<TAB>isp<TAB>IMAP<TAB>hostname
  79 XFER 0 15
  80 XFER 15 15
  81 imap.server.com
  82 ]]></screen><para>Remember that in interactive mode and when not doing a server inquire, you will need to press CTRL-V before pressing TAB.</para>
  83 <para>The XFER lines are status messages. They show the current and total length of the data transfered in bytes. The last line is the value of the element path we just created.</para>
  84 <para>Let us create the rest of the needed elements:</para><screen>
  85 <![CDATA[pwm> STORE email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
  86 pwm> STORE
  87 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
  88 pwm> STORE
  89 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
  90 pwm> STORE
  91 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
  92 ]]></screen><para>Now the element structure for the root "email" element looks like this:</para><screen>
  93 <![CDATA[<email>
  94     <isp>
  95         <IMAP>
  96               <hostname>imap.server.com</hostname>
  97               <port>993</port>
  98               <ssl>1</ssl>
  99         </IMAP>
 100         <username>myusername</username>
 101         <password>mypassword</password>
 102     </isp>
 103 </email>
 104 ]]></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>
 105 <![CDATA[pwm> STORE
 106 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
 107 ]]></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>
 108 <![CDATA[pwm> <CTRL-D>
 109 ]]></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>
 110 <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 pwmd documentation for details.</para>
 111 <para>Various applications using libpwmd may have different element path requirements. Refer to the documentation of each application that supports pwmd for the required elements.</para></sect1><sect1 id='sec.Linking-elements-1' >
 112 <title><!-- anchor id="sec.Linking-elements-1" -->Linking elements</title>
 113 <para>One distinguishing feature of pwmd is the ability to share data of an element path with another. For example, if your ISP lets you host a blog on their server and you use a blogging client that supports pwmd to edit your posts, 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>
 114 <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>
 115 <para>Let's create an example blogging element path:</para><screen>
 116 <![CDATA[pwm> STORE
 117 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
 118
 119 pwm> ATTR SET target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
 120 pwm> ATTR SET target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
 121 ]]></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 get 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>
 122 <![CDATA[pwm> GET blog<TAB>isp<TAB>!password
 123 ERR 536870938: No value
 124 ]]></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>
 125 <![CDATA[pwmd> STORE
 126 blog<TAB>isp<TAB>!password<TAB>newpassword<CTRL-D><CTRL-D>
 127 ]]></screen><para>Now when we redo the previous GET command:</para><screen>
 128 <![CDATA[pwm> GET blog<TAB>isp<TAB>!password
 129 XFER 0 11
 130 XFER 11 11
 131 newpassword
 132 ]]></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>
 133 <![CDATA[pwm> GET blog<TAB>isp<TAB>password
 134 XFER 0 10
 135 XFER 10 10
 136 mypassword
 137 ]]></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>
 138 <![CDATA[pwm> REALPATH blog<TAB>isp<TAB>password
 139 XFER 0 30
 140 XFER 30 30
 141 !email<TAB>!isp<TAB>!password
 142 ]]></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>
 143 <para>Using the LIST command is useful to show the element structure of a document. The XFER status messages have been omitted:</para><screen>
 144 <![CDATA[pwm> LIST
 145 !email
 146 !blog
 147 pwm> LIST !email
 148 !email
 149 !email<TAB>!isp
 150 !email<TAB>!isp<TAB>!username
 151 !email<TAB>!isp<TAB>!password
 152 !email<TAB>!isp<TAB>!IMAP<TAB>!hostname
 153 !email<TAB>!isp<TAB>!IMAP<TAB>!port
 154 !email<TAB>!isp<TAB>!IMAP<TAB>!ssl
 155 pwm> LIST !blog
 156 !blog
 157 !blog<TAB>!isp
 158 !blog<TAB>!isp<TAB>!username
 159 !blog<TAB>!isp<TAB>username
 160 !blog<TAB>!isp<TAB>!password
 161 !blog<TAB>!isp<TAB>password
 162 ]]></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>
 163 <para>For the final example, we will remove the &ldquo;target&rdquo; attribute of the blogging password element:</para><screen>
 164 <![CDATA[pwm> ATTR DELETE target blog<TAB>isp<TAB>!password
 165 ]]></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>
 166 <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>
 167 <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>