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.3.1
   9   See http://www.lyx.org/ for more information -->
  10 <article lang="en">
  11 <articleinfo>
  12 <title>Libpwmd Tutorial</title>
  13 <date>Sep-21-2016</date><author>
  14 Ben Kibbey<footnote><thanks>bjk@luxsci.net</thanks></footnote><toc></toc></author></articleinfo><sect1>
  15 <title>Introduction</title>
  16 <para>This is a tutorial showing the basic usage of libpwmd<footnote><footnote>https://gitlab.com/bjk/libpwmd/wikis</footnote></footnote>. Libpwmd<emphasis> </emphasis>is a library making it easy for applications to use pwmd<footnote><footnote>https://gitlab.com/bjk/pwmd/wikis</footnote></footnote> (<emphasis>Password Manager Daemon). Password Manager Daemon</emphasis> is a universal data server. It began as a way to keep track of passwords for accounts like email and websites but has evolved to store anything you want. There are other password management tools but pwmd has a couple of distinguishing features:</para><itemizedlist>
  17 <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-0"> for details.</para></listitem><listitem><para>The XML document is OpenPGP encrypted and signed using an existing or newly generated key pair. Symmetric encryption is also supported as well as smartcards. All crypto operations are done using GpgME which in turn uses gnupg.</para></listitem></itemizedlist><para>Other features include:</para><itemizedlist>
  18 <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><listitem><para>Remote connections over SSH (some configuration needed).</para></listitem><listitem><para>ACL's for each element in an element path, listening socket and filename.</para></listitem></itemizedlist></sect1><sect1>
  19 <title>File Format and Element Paths</title>
  20 <para>The document is in XML format and is manipulated by commands sent from a client. Commands that access previously stored data take what is called an <emphasis>element path</emphasis> as an argument. An element path is a character string containing 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 since it would be an XML syntax error. For the rest of this tutorial, when you see &lt;TAB&gt;, replace it with a real TAB character.</para>
  21 <para>For example, the element path "root&lt;TAB&gt;child&lt;TAB&gt;last" has the following element tree structure:</para><screen>
  22 <![CDATA[<root>
  23     <child>
  24         <last>
  25 Content or XML CDATA of the "last" element.
  26         </last>
  27     </child>
  28 </root>
  29 ]]></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>
  30 <![CDATA[<element _name="root">
  31     <element _name="child">
  32         <element _name="last">
  33 Content or CDATA of the "last" element.
  34         </element>
  35     </element>
  36 </element>
  37 ]]></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.</para>
  38 <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>
  39 <![CDATA[<root>
  40     <child>
  41         <last>
  42 Content or XML CDATA of the "last" element.
  43         </last>
  44     </child>
  45     <child>
  46 This element will never be reached.
  47     </child>
  48 </root>
  49 ]]></screen><para>The second "&lt;child&gt;" element is never reached because it has the same name as its sibling element &ldquo;above&rdquo; it.</para></sect1><sect1>
  50 <title>Connecting to PWMD</title>
  51 <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><footnote>https://gitlab.com/bjk/qpwmc/wikis</footnote></footnote> which uses the Qt4 or Qt5 toolkit and is also a full featured client.</para>
  52 <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 (UDS) that pwmd waits for connections on and use interactive mode. Remote connections are also 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>
  53 <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>
  54 <![CDATA[$ pwmc datafile
  55 Connected.
  56 pwmc:datafile>
  57 ]]></screen><para>The "pwmc&gt;" prompt is a readline prompt that has command history and can also do filename completion when doing a dot command that requires a filename on the local filesystem.</para></sect1><sect1>
  58 <title>Commands</title>
  59 <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 dot '.' followed by the command name. Protocol commands are sent without any dot prefix. To see the available pwmc and protocol commands, send the .help or HELP commands:</para><screen>
  60 <![CDATA[pwmc:datafile> .help
  61 ]]></screen><para>or</para><screen>
  62 <![CDATA[pwmc:datafile> help
  63 ]]></screen><para>To store some data in an element path or to create 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>
  64 <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>
  65 <![CDATA[pwmc:datafile> STORE
  66 Press CTRL-D to send the current line. Press twice to end. DATA:
  67 ]]></screen><para>The STORE command is a <emphasis>pwmd</emphasis> protocol command. This, and a few other commands, use what is called a <emphasis>server inquire</emphasis> to retrieve additional command parameters from the client while other commands require only the command itself with its 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 informing 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[email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
  69 ]]></screen><para>Remember that you should replace &lt;TAB&gt; in the examples with a real TAB character. After pressing the first &lt;CTRL-D&gt;, the characters that were entered are 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>
  70 <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>
  71 <para>We have just created an element path whose XML structure looks like the following:</para><screen>
  72 <![CDATA[<email>
  73     <isp>
  74         <IMAP>
  75             <hostname>imap.server.com</hostname>
  76         </IMAP>
  77     </isp>
  78 </email>
  79 ]]></screen><para>The GET protocol command returns the value, or content, of the last element of an element path. To retrieve the hostname of the element path we just created, do:</para><screen>
  80 <![CDATA[pwmc:datafile> GET email<TAB>isp<TAB>IMAP<TAB>hostname
  81 imap.server.com
  82 pwmc:datafile>
  83 ]]></screen><para>Let us create the rest of the needed elements:</para><screen>
  84 <![CDATA[pwmc:datafile> STORE
  85 email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
  86
  87 pwmc:datafile> STORE
  88 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
  89
  90 pwmc:datafile> STORE
  91 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
  92
  93 pwmc:datafile> STORE
  94 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
  95 ]]></screen><para>Now the element structure for the "email" element looks like this:</para><screen>
  96 <![CDATA[<email>
  97     <isp>
  98         <IMAP>
  99               <hostname>imap.server.com</hostname>
 100               <port>993</port>
 101               <ssl>1</ssl>
 102         </IMAP>
 103         <username>myusername</username>
 104         <password>mypassword</password>
 105     </isp>
 106 </email>
 107 ]]></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>
 108 <![CDATA[pwmc:datafile> STORE
 109 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
 110 pwmc:datafile>
 111 ]]></screen><para>An application using libpwmd that requires mail server information now has the basic information it needs. It may require more elements and they can be created just as these elements have been. The only thing left to do now is to save the changes:</para><screen>
 112 <![CDATA[pwmc:datafile> <CTRL-D>
 113 ]]></screen><para>After pressing &lt;CTRL-D&gt; a prompt will be shown asking what to do next. Press &ldquo;s&rdquo; to save what we have created. This will generate a new encryption and signing key pair by default. If you would rather use an existing encryption and signing key or use symmetric encryption, you will need to use the .save pwmc command along with the required SAVE protocol command options. The .save command lets libpwmd set some things that may be needed for the current connection such as pinentry settings. Type:</para><screen>
 114 <![CDATA[pwmc:datafile> help save
 115 ]]></screen><para>to see SAVE syntax and options.</para>
 116 <para>When the save has completed the encrypted data file has been written to disk and is also stored in pwmd's file cache. A cached document is the same document on disc that is stored in memory. This means that the next time the document is opened a passphrase won't be required until pwmd's cache timer removes it from the cache. By default, the cache timeout for each data file is 600 seconds, or 10 minutes. This setting can be changed in pwmd's configuration and set independently for each file and can also be set to not cache the file at all or to cache it indefinately.</para></sect1><sect1 id='sec.Linking-elements-0' >
 117 <title><!-- anchor id="sec.Linking-elements-0" -->Linking elements</title>
 118 <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>
 119 <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>
 120 <para>Let's create an example blogging element path:</para><screen>
 121 <![CDATA[pwmc:datafile> STORE
 122 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
 123
 124 pwmc:datafile> ATTR SET _target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
 125 pwmc:datafile> ATTR SET _target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
 126 ]]></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, just use the GET command as you would for any other element:</para><screen>
 127 <![CDATA[pwmc:datafile> GET blog<TAB>isp<TAB>password
 128 mypassword
 129 pwmc:datafile>
 130 ]]></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 protocol command:</para><screen>
 131 <![CDATA[pwmc:datafile> REALPATH blog<TAB>isp<TAB>password
 132 email<TAB>isp<TAB>password
 133 pwmc:datafile>
 134 ]]></screen><para>Using the LIST command is useful to show the element structure of a document:</para><screen>
 135 <![CDATA[pwmc:datafile> LIST
 136 email
 137 blog
 138 pwmc:datafile> LIST email
 139 email
 140 email<TAB>isp
 141 email<TAB>isp<TAB>username
 142 email<TAB>isp<TAB>password
 143 email<TAB>isp<TAB>IMAP<TAB>hostname
 144 email<TAB>isp<TAB>IMAP<TAB>port
 145 email<TAB>isp<TAB>IMAP<TAB>ssl
 146 pwmc:datafile> LIST blog
 147 blog
 148 blog<TAB>isp
 149 blog<TAB>isp<TAB>hostname
 150 blog<TAB>isp<TAB>username
 151 blog<TAB>isp<TAB>password
 152 pwmc:datafile>
 153 ]]></screen></sect1></article>