1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 >Libpwmd Tutorial
</TITLE
8 CONTENT=
"Modular DocBook HTML Stylesheet Version 1.79"></HEAD
37 >This is a tutorial showing the basic usage of libpwmd
<A
50 >is a library making it easy for applications to use pwmd
<A
61 >Password Manager Daemon). Password Manager Daemon
</I
63 > 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:
</P
69 >It does not depend on a desktop environment but has the ability for applications to connect to it like a desktop solution provides.
</P
73 >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
<A
74 HREF=
"#SEC.LINKING-ELEMENTS-0"
75 >the Section called
<I
82 >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.
</P
86 >Other features include:
</P
92 >Multi-threaded. More than one client may access the same data file while optionally locking out other clients.
</P
96 >Secure memory management. Pwmd will zero out memory before freeing it and the contents of the cached document are encrypted.
</P
100 >Remote connections over TLS with client certificates used as authentication.
</P
104 >Remote connections over SSH (some configuration needed).
</P
108 >ACL's for each element in an element path, listening socket and filename.
</P
118 >File Format and Element Paths
</A
121 >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
<SPAN
127 > 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
<TAB
>, replace it with a real TAB character.
</P
129 >For example, the element path
"root<TAB>child<TAB>last" has the following element tree structure:
</P
141 Content or XML CDATA of the
"last" element.
149 >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:
</P
158 ><element
_name=
"root">
159 <element
_name=
"child">
160 <element
_name=
"last">
161 Content or CDATA of the
"last" element.
164 </element
></PRE
169 >Every element created has an element named
<SPAN
175 > with an attribute
<SPAN
181 > associated with it. The value of the
<SPAN
187 > 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.
</P
189 >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:
</P
201 Content or XML CDATA of the
"last" element.
205 This element will never be reached.
212 >The second
"<child>" element is never reached because it has the same name as its sibling element
“above
” it.
</P
220 >Connecting to PWMD
</A
223 >You will need a
<SPAN
229 > client to send commands to the pwmd server.
<SPAN
235 > includes a client named
<SPAN
241 >. It is command-line based and there are not any fancy graphics, but it is good for understanding how
<SPAN
247 > 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
<A
254 > which uses the Qt4 or Qt5 toolkit and is also a full featured client.
</P
256 >In this tutorial we will use the
<SPAN
262 > client included with libpwmd.
<SPAN
268 > 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.
</P
270 >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:
</P
281 pwmc:datafile
></PRE
286 >The
"pwmc>" 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.
</P
297 >There are two different types of commands: client commands and protocol commands. The client commands are
<SPAN
303 > specific and only available to the
<SPAN
309 > client. Protocol commands are commands sent from any client and to the
<SPAN
315 > 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:
</P
324 >pwmc:datafile
> .help
</PRE
338 >pwmc:datafile
> help
</PRE
343 >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.
</P
345 >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:
</P
354 >pwmc:datafile
> STORE
355 Press CTRL-D to send the current line. Press twice to end. DATA:
</PRE
360 >The STORE command is a
<SPAN
366 > protocol command. This, and a few other commands, use what is called a
<SPAN
372 > 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
<CTRL-D
> twice to finish sending the data and to let
<SPAN
378 > complete the command:
</P
387 >email
<TAB
>isp
<TAB
>IMAP
<TAB
>hostname
<TAB
>imap.server.com
<CTRL-D
><CTRL-D
></PRE
392 >Remember that you should replace
<TAB
> in the examples with a real TAB character. After pressing the first
<CTRL-D
>, the characters that were entered are sent to
<SPAN
398 > and the inquire continues. To terminate the inquire and finish sending data for the command press
<CTRL-D
> a second time.
</P
400 >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.
</P
402 >We have just created an element path whose XML structure looks like the following:
</P
414 <hostname
>imap.server.com
</hostname
>
417 </email
></PRE
422 >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:
</P
431 >pwmc:datafile
> GET email
<TAB
>isp
<TAB
>IMAP
<TAB
>hostname
433 pwmc:datafile
></PRE
438 >Let us create the rest of the needed elements:
</P
447 >pwmc:datafile
> STORE
448 email
<TAB
>isp
<TAB
>IMAP
<TAB
>port
<TAB
>993<CTRL-D
><CTRL-D
>
450 pwmc:datafile
> STORE
451 email
<TAB
>isp
<TAB
>IMAP
<TAB
>ssl
<TAB
>1<CTRL-D
><CTRL-D
>
453 pwmc:datafile
> STORE
454 email
<TAB
>isp
<TAB
>username
<TAB
>myusername
<CTRL-D
><CTRL-D
>
456 pwmc:datafile
> STORE
457 email
<TAB
>isp
<TAB
>password
<TAB
>mypassword
<CTRL-D
><CTRL-D
></PRE
462 >Now the element structure for the
"email" element looks like this:
</P
474 <hostname
>imap.server.com
</hostname
>
475 <port
>993</port
>
476 <ssl
>1</ssl
>
478 <username
>myusername
</username
>
479 <password
>mypassword
</password
>
481 </email
></PRE
486 >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:
</P
495 >pwmc:datafile
> STORE
496 email
<TAB
>isp
<TAB
>password
<TAB
>newpassword
<CTRL-D
><CTRL-D
>
497 pwmc:datafile
></PRE
502 >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:
</P
511 >pwmc:datafile
> <CTRL-D
></PRE
516 >After pressing
<CTRL-D
> a prompt will be shown asking what to do next. Press
“s
” 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:
</P
525 >pwmc:datafile
> help save
</PRE
530 >to see SAVE syntax and options.
</P
532 >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.
</P
539 NAME=
"SEC.LINKING-ELEMENTS-0"
543 >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.
</P
545 >This is done by setting a special
“target
” attribute for an element. It behaves similarly to the HTML
“target
” attribute or XML entities or a symbolic link on a filesystem.
</P
547 >Let's create an example blogging element path:
</P
556 >pwmc:datafile
> STORE
557 blog
<TAB
>isp
<TAB
>hostname
<TAB
>blog.myisp.com
<CTRL-D
><CTRL-D
>
559 pwmc:datafile
> ATTR SET target blog
<TAB
>isp
<TAB
>username email
<TAB
>isp
<TAB
>username
560 pwmc:datafile
> ATTR SET target blog
<TAB
>isp
<TAB
>password email
<TAB
>isp
<TAB
>password
</PRE
565 >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:
</P
574 >pwmc:datafile
> GET blog
<TAB
>isp
<TAB
>password
576 pwmc:datafile
></PRE
581 >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:
</P
590 >pwmc:datafile
> REALPATH blog
<TAB
>isp
<TAB
>password
591 email
<TAB
>isp
<TAB
>password
592 pwmc:datafile
></PRE
597 >Using the LIST command is useful to show the element structure of a document:
</P
606 >pwmc:datafile
> LIST
609 pwmc:datafile
> LIST email
611 email
<TAB
>isp
612 email
<TAB
>isp
<TAB
>username
613 email
<TAB
>isp
<TAB
>password
614 email
<TAB
>isp
<TAB
>IMAP
<TAB
>hostname
615 email
<TAB
>isp
<TAB
>IMAP
<TAB
>port
616 email
<TAB
>isp
<TAB
>IMAP
<TAB
>ssl
617 pwmc:datafile
> LIST blog
620 blog
<TAB
>isp
<TAB
>hostname
621 blog
<TAB
>isp
<TAB
>username
622 blog
<TAB
>isp
<TAB
>password
623 pwmc:datafile
></PRE
655 >bjk@luxsci.net
</FONT
692 >http://libpwmd.sourceforge.net/
</TD
713 >http://libpwmd.sourceforge.net/
</TD
749 >http://pwmd.sourceforge.net/
</TD
770 >http://pwmd.sourceforge.net/
</TD
806 >http://qpwmc.sourceforge.net/
</TD
827 >http://qpwmc.sourceforge.net/
</TD