1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
6 \use_default_options false
7 \maintain_unincluded_children false
9 \language_package default
14 \font_typewriter default
15 \font_default_family default
16 \use_non_tex_fonts false
23 \default_output_format default
25 \bibtex_command default
26 \index_command default
27 \paperfontsize default
39 \paperorientation portrait
48 \paragraph_separation indent
49 \paragraph_indentation default
50 \quotes_language english
53 \paperpagestyle default
54 \tracking_changes false
76 \begin_layout Plain Layout
86 \begin_inset CommandInset toc
87 LatexCommand tableofcontents
98 \begin_layout Standard
99 This is a tutorial showing the basic usage of libpwmd
103 \begin_layout Plain Layout
104 http://libpwmd.sourceforge.net/
114 is a library making it easy for applications to use pwmd
118 \begin_layout Plain Layout
119 http://pwmd.sourceforge.net/
126 Password Manager Daemon).
127 Password Manager Daemon
129 is a universal data server.
130 It began as a way to keep track of my passwords for accounts like email
131 and websites but can be used to store anything you want.
134 \begin_layout Standard
135 There are other password management tools but pwmd has a couple of distinguishin
139 \begin_layout Itemize
140 It does not depend on a desktop environment but has the ability for applications
141 to connect to it like a desktop solution provides.
144 \begin_layout Itemize
145 Some portion of a stored data can be shared with another portion in the
147 This feature behaves a lot like a symbolic link on a file system, XML entities,
148 or HTML targets if you're familiar with those, but implemented in a different
150 This means less duplication of content.
152 \begin_inset CommandInset ref
154 reference "sec:Linking-elements"
161 \begin_layout Itemize
162 The document is encrypted with GnuPG and uses gpg-agent for passphrase handling.
163 GnuPG supports both symmetric and PKI encryption and smartcards are also
167 \begin_layout Standard
168 Other features include:
171 \begin_layout Itemize
173 More than one client may access the same data file while optionally locking
177 \begin_layout Itemize
178 Secure memory management.
179 Pwmd will zero out memory before freeing it and the contents of the cached
180 document are encrypted.
183 \begin_layout Itemize
184 Remote connections over TLS with client certificates used as authentication.
187 \begin_layout Section
188 File Format and Element Paths
191 \begin_layout Standard
192 The document is saved as an XML document and is manipulated by commands
194 Commands that access data take what is called an
199 An element path is a character string containing XML element names representing
200 branches of an element tree.
201 The branches are separated with a TAB (ASCII 0x09) character.
202 Why a TAB? So other characters can be used in the element name.
203 If for example a '/' were used as the separator, then a URL (i.e., http://sf.net/)
204 could not be used as an element name.
207 \begin_layout Standard
208 For the rest of this tutorial, when you see <TAB>, replace it with a real
210 For example, the element path "a<TAB>child<TAB>last" has the following
231 Content or XML CDATA of the "last" element.
249 \begin_layout Standard
250 I should say that the XML structure that pwmd uses is a little more complicated.
251 It really looks like the following internally, but we will use the above
252 format in this tutorial for simplicity:
257 <element _name="root">
262 <element _name="child">
267 <element _name="last">
272 Content or CDATA of the "last" element.
290 \begin_layout Standard
291 Every element created has an element named
304 attribute is what an element in an element path refers to.
305 It is done this way so that a wider range of characters can be used in
306 an element name while maintaining valid XML.
307 In fact, the only restriction of an element name is that it not contain
308 whitespace characters and not begin with an exclamation point (ASCII 0x21
313 \begin_inset CommandInset ref
315 reference "sec:Linking-elements"
324 \begin_layout Standard
325 There is one other difference from your normal XML document in that only
326 the first match of an element is considered for the current element tree
328 When an element of the current depth of an element tree is found, the next
329 element in the element path is searched for beginning at the child node
330 of the found element.
331 From the example above:
351 Content or XML CDATA of the "last" element.
371 This element will never be reached.
384 \begin_layout Standard
385 The second "child" element is never reached.
388 \begin_layout Section
392 \begin_layout Standard
397 client to send commands to the pwmd server.
402 includes a client named
407 It is command-line based and there are not any fancy graphics, but it is
408 good for understanding how
412 commands are processed.
413 If you want a more user friendly client that resembles a file manager and
414 has a point and click interface, try qpwmc
418 \begin_layout Plain Layout
419 http://qpwmc.sourceforge.net/
424 which uses the Qt4 toolkit and is also a full featured client.
427 \begin_layout Standard
428 In this tutorial we will use the
432 client included with libpwmd.
437 has two modes that commands are read from: interactive and stdin.
438 The interactive mode uses the readline library and has command history
439 while reading from standard input (stdin) makes shell scripting and automation
441 For the examples, we will be connecting to the default local unix domain
442 socket that pwmd waits for connections on.
443 Remote connections are possible over TLS or an SSH channel but those are
445 Read the pwmc(1) manual page for details about how to do that.
448 \begin_layout Standard
449 The example filename we will use is "datafile".
450 It is initially a non-existent file but it will be created once we have
452 Now let us connect to the server in interactive mode and open the data
471 \begin_layout Standard
472 The "pwm>" prompt is a readline prompt that has command history and can
473 do filename completion.
474 It also is annoying because, as mentioned, elements in element paths are
475 TAB delimited, but command completion in readline uses the TAB character,
477 To insert a real TAB character in interactive mode rather than do readline
478 completion, you will need to first press CTRL-V and then press TAB.
481 \begin_layout Section
485 \begin_layout Standard
486 There are two different types of commands: client commands and protocol
488 The client commands are
492 specific and only available to the
497 Protocol commands are commands sent from any client and to the
502 All pwmc client commands are prefixed with a period '.' followed by the
504 Protocol commands are sent without any prefix.
505 To see the available pwmc and protocol commands, send the HELP command:
512 \begin_layout Standard
520 \begin_layout Standard
521 To store some data in an element path, you will need to know what element
523 It is up to you how you want your data organized.
524 If for example you will be storing account information it may be good to
525 categorize what the account is for: email, instant messaging, blogging,
527 An application that uses libpwmd may require that a certain element path
529 Refer to that applications documentation to determine what element paths
533 \begin_layout Standard
534 In the following example we will setup mail server element paths which can
535 be used for other applications requiring a mail server configuration.
536 First, lets create the hostname element path:
544 \begin_layout Standard
545 The STORE command is a
550 This command, and some other commands, use what is called a
554 to retrieve data from the client while other commands may retrieve the
555 data only from the command arguments.
556 The server inquire will wait for the client to finish sending its data
557 before completing the command.
558 When responding to a server inquire in pwmc, pwmc will show a message telling
559 you that it is waiting for data to be sent.
560 Enter the element path and its content, then press <CTRL-D> twice to finish
561 sending the data and to let
565 complete the command:
575 email<TAB>isp<TAB>IMAP<TAB>hostname<TAB>imap.server.com<CTRL-D><CTRL-D>
578 \begin_layout Standard
579 Remember that you should replace <TAB> in the examples with a real TAB character.
580 I should mention that when sending data via a server inquire there is no
581 need to press <CTRL-V> to insert the <TAB> character.
582 That is only needed from the readline command prompt and when not doing
586 \begin_layout Standard
587 After pressing the first <CTRL-D>, the line that was entered is sent to
592 and the inquire continues.
593 To terminate the inquire and finish sending data for the command, press
594 <CTRL-D> a second time.
597 \begin_layout Standard
598 If you were to have pressed <RETURN> before any <CTRL-D> then the inquired
599 line would have been sent in full including a newline character.
600 Since in this example a newline character in a hostname is not a valid
601 hostname, this is not what we want.
604 \begin_layout Standard
605 We have just created an element path whose XML structure looks like the
626 <hostname>imap.server.com</hostname>
644 \begin_layout Standard
645 The GET protocol command returns the value of the last element of an element
647 To retrieve the hostname of the element path we just created, do:
652 pwm> GET email<TAB>isp<TAB>IMAP<TAB>hostname
660 \begin_layout Standard
661 Remember that in interactive mode and when not doing a server inquire, you
662 will need to press <CTRL-V> before pressing <TAB>.
665 \begin_layout Standard
666 Let us create the rest of the needed elements:
676 email<TAB>isp<TAB>IMAP<TAB>port<TAB>993<CTRL-D><CTRL-D>
686 email<TAB>isp<TAB>IMAP<TAB>ssl<TAB>1<CTRL-D><CTRL-D>
696 email<TAB>isp<TAB>username<TAB>myusername<CTRL-D><CTRL-D>
706 email<TAB>isp<TAB>password<TAB>mypassword<CTRL-D><CTRL-D>
709 \begin_layout Standard
710 Now the element structure for the "email" element looks like this:
730 <hostname>imap.server.com</hostname>
750 <username>myusername</username>
755 <password>mypassword</password>
768 \begin_layout Standard
769 If you wanted to change your password (after changing it on the mail server,
770 of course) just do as you did when initially creating the password element
772 The new content will overwrite the existing content:
782 email<TAB>isp<TAB>password<TAB>newpassword<CTRL-D><CTRL-D>
785 \begin_layout Standard
786 An application using libpwmd that needs to know mail server information
787 now has all the information it needs.
788 The only thing left to do now is to save the changes:
796 \begin_layout Standard
797 After pressing <CTRL-D> a prompt will be shown asking what to do.
799 \begin_inset Quotes eld
803 \begin_inset Quotes erd
806 to save what we have created.
809 \begin_layout Standard
810 Since this is a new file, you will be prompted for a passphrase to use for
812 Once done, the data file is encrypted and written to disk and the passphrase
813 is cached in pwmd so you do not need to enter it the next time your data
814 file is opened or saved.
815 There are a few pwmd configuration parameters that affect how this operates.
820 documentation for details.
823 \begin_layout Section
824 \begin_inset CommandInset label
826 name "sec:Linking-elements"
833 \begin_layout Standard
834 One distinguishing feature of pwmd is the ability to share data of one element
836 If for example your ISP lets you host a blog on their server and you use
837 a blogging client that can use libpwmd for authentication details, you
838 can share authentication information with the email example above when
839 the account details are the same.
840 When element linking is used, this avoids the need to change the content
841 for both the blogging and email password elements.
844 \begin_layout Standard
845 This is done by setting a special
846 \begin_inset Quotes eld
850 \begin_inset Quotes erd
853 attribute for an element.
854 It behaves similarly to the HTML
855 \begin_inset Quotes eld
859 \begin_inset Quotes erd
862 attribute or XML entities or a symbolic link on a filesystem.
866 \begin_layout Standard
867 Let's create an example blogging element path:
877 blog<TAB>isp<TAB>hostname<TAB>blog.myisp.com<CTRL-D><CTRL-D>
886 pwm> ATTR SET target blog<TAB>isp<TAB>username email<TAB>isp<TAB>username
891 pwm> ATTR SET target blog<TAB>isp<TAB>password email<TAB>isp<TAB>password
894 \begin_layout Standard
895 Now each access of the "blog/isp/username" and "blog/isp/password" element
896 paths, which were created if they did not already exist, will point to
897 "email/isp/username" and "email/isp/password" respectively.
898 To retrieve the value or content of an element that contains a "target"
899 attribute without following any
900 \begin_inset Quotes eld
904 \begin_inset Quotes erd
907 attribute, prefix the element with a '!' when specifying it in an element
914 pwm> GET blog<TAB>isp<TAB>!password
919 ERR 536870938: No value
922 \begin_layout Standard
923 An error is returned because we have not assigned a value to the literal
925 A literal element is an element that either contains no "target" attribute
926 or ignores it by prefixing the element with the mentioned literal element
928 Let us try storing an example password to the literal element to show usage:
938 blog<TAB>isp<TAB>!password<TAB>literalpassword<CTRL-D><CTRL-D>
941 \begin_layout Standard
942 Now when we redo the previous GET command:
947 pwm> GET blog<TAB>isp<TAB>!password
955 \begin_layout Standard
956 This is the value of the literal password element of the element path.
957 To follow the element path stored in the "target" attribute, omit the '!'
958 in the password element.
960 \begin_inset Quotes eld
964 \begin_inset Quotes erd
972 pwm> GET blog<TAB>isp<TAB>password
980 \begin_layout Standard
981 A "target" attribute may also refer to another element with a "target" attribute.
982 Every "target" attribute will be followed until there are no others to
984 To get the real element path and resolve all "target" attributes, use the
990 pwm> REALPATH blog<TAB>isp<TAB>password
995 !email<TAB>!isp<TAB>!password
998 \begin_layout Standard
999 As you can see each element is prefixed with the literal '!' character meaning
1000 that no "target" attribute exists in any element of the resulting element
1004 \begin_layout Standard
1005 Using the LIST command is useful to show the element structure of a document:
1040 !email<TAB>!isp<TAB>!username
1045 !email<TAB>!isp<TAB>!password
1050 !email<TAB>!isp<TAB>!IMAP<TAB>!hostname
1055 !email<TAB>!isp<TAB>!IMAP<TAB>!port
1060 !email<TAB>!isp<TAB>!IMAP<TAB>!ssl
1080 !blog<TAB>!isp<TAB>!username
1085 !blog<TAB>!isp<TAB>username
1090 !blog<TAB>!isp<TAB>!password
1095 !blog<TAB>!isp<TAB>password
1098 \begin_layout Standard
1099 Notice that there are two username and password elements in the
1100 \begin_inset Quotes eld
1104 \begin_inset Quotes erd
1107 element path: each with and without the literal element character prefix.
1108 This shows that both the username and password elements contain a "target"
1112 \begin_layout Standard
1113 For the final example, we will remove the
1114 \begin_inset Quotes eld
1118 \begin_inset Quotes erd
1121 attribute of the blogging password element:
1126 pwm> ATTR DELETE target blog<TAB>isp<TAB>!password
1129 \begin_layout Standard
1130 If we were to have omitted the '!' from the password element then pwmd would
1131 try to remove the "target" attribute from the "email/isp/password" element
1133 That would return an error because no
1134 \begin_inset Quotes eld
1138 \begin_inset Quotes erd
1141 attribute had been set for that element.
1144 \begin_layout Standard
1145 Note that the "blog" and "isp" elements have no literal element character
1146 prepended to them in the example.
1147 It is not needed because they have no
1148 \begin_inset Quotes eld
1152 \begin_inset Quotes erd
1155 attribute themselves.
1158 \begin_layout Standard
1160 \begin_inset Quotes eld
1164 \begin_inset Quotes erd
1167 attributes can be confusing.
1168 The best way to get the hang of linking elements is to experiment and use
1169 the LIST and DUMP commands to show the document structure.
1170 Remember to use the literal element prefix '!' when you do not want to
1171 follow any "target" attributes.