projects/pwm

view pwm.1.xml @ 23:1b89066d992c

Add read-only mode
author Guido Berhoerster <guido+pwm@berhoerster.name>
date Sun Sep 17 18:45:05 2017 +0200 (2017-09-17)
parents ec01c579024a
children 5bdea77d0c1d
line source
1 <?xml version="1.0"?>
2 <!--
4 Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name>
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook"
27 xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
28 <info>
29 <author>
30 <personname>
31 <firstname>Guido</firstname>
32 <surname>Berhoerster</surname>
33 </personname>
34 <email>guido+pwm@berhoerster.name</email>
35 <personblurb/>
36 </author>
37 <date>17 September, 2017</date>
38 </info>
39 <refmeta>
40 <refentrytitle>pwm</refentrytitle>
41 <manvolnum>1</manvolnum>
42 <refmiscinfo class="source"/>
43 <refmiscinfo class="version"/>
44 <refmiscinfo class="manual">User Commands</refmiscinfo>
45 </refmeta>
46 <refnamediv>
47 <refname>pwm</refname>
48 <refpurpose>password manager</refpurpose>
49 </refnamediv>
50 <refsynopsisdiv>
51 <cmdsynopsis>
52 <command>pwm</command>
53 <arg choice="opt">
54 <option>-P</option>
55 <replaceable>password_file</replaceable>
56 </arg>
57 <arg choice="opt">
58 <option>-R</option>
59 </arg>
60 <arg choice="opt">
61 <replaceable>database_file</replaceable>
62 </arg>
63 </cmdsynopsis>
64 </refsynopsisdiv>
65 <refsect1>
66 <title>Description</title>
67 <para>The <command>pwm</command> utility is a password manager which
68 stores passwords and associated metadata in an encrypted database protected
69 by a master password. It offers both a text-based user interface for
70 interactive use as well as a non-interactive mode. The database uses the
71 PasswordSafe database version 3 file format and thus provides
72 interoperabity with other password managers using the same format.</para>
73 <para>After opening an existing database or creating a new one,
74 <command>pwm</command> provides commands to create, modify, delete, and
75 display password database entries which may be organized in groups. The
76 contents of a field of a given entry can also be piped to an external
77 command, e.g. in order to copy the content of the username or password
78 field of an entry to the clipboard.</para>
79 <para>If specified, <command>pwm</command> will open or create
80 <replaceable>database_file</replaceable> instead of the user's default
81 database.</para>
82 <para><command>pwm</command> must be run with a locale which uses the UTF-8
83 character encoding.</para>
84 <refsect2>
85 <title>Output format</title>
86 <para>The <command>show</command> and <command>info</command> commands
87 display fields by printing the field name followed by a colon, one or
88 more space characters and the field's verbatim content to the standard
89 output stream. Field content may contain newlines, non-printable and/or
90 control characters.</para>
91 <para>If running in interactive mode, the <command>list</command>,
92 <command>show</command> and <command>info</command> will display
93 the results on a page-by-page basis using an internal pager.</para>
94 <para>The <command>pipe</command> prints the verbatim field content to the
95 standard input stream of the given command.</para>
96 <para>Error messages are printed to the standard error stream.</para>
97 </refsect2>
98 </refsect1>
99 <refsect1>
100 <title>Options</title>
101 <para>The following options are supported:</para>
102 <variablelist>
103 <varlistentry>
104 <term>
105 <option>-P</option>
106 <replaceable>password_file</replaceable>
107 </term>
108 <listitem>
109 <para>Read the master password from the first line of
110 <replaceable>password_file</replaceable>.</para>
111 </listitem>
112 </varlistentry>
113 <varlistentry>
114 <term>
115 <option>-R</option>
116 </term>
117 <listitem>
118 <para>Treat the database as read-only and disallow any modifications
119 and write operations.</para>
120 </listitem>
121 </varlistentry>
122 </variablelist>
123 </refsect1>
124 <refsect1>
125 <title>Usage</title>
126 <para>If stdin is connected to a terminal pwm will run in interactive mode
127 and prompt the user for the master password unless
128 <replaceable>password_file</replaceable> is specified via the
129 <option>-P</option> option. After successfully opening the password
130 database the user will be prompted for a command.</para>
131 <para>When running in non-interactive mode a file containing the master
132 pasword must be specified via the <option>-P</option> option and after
133 successfully opening the password database, pwm will execute commands read
134 from stdin until either an error occurrs or end-of-file is reached.</para>
135 <para><command>pwm</command> operates on a copy of the password database
136 in memory, any changes must be explicitly written back to the database
137 using the write command.</para>
138 <refsect2>
139 <title>IDs</title>
140 <para>Database entries are referred to by an ID value which is a
141 positive integer value that is guaranteed to be unqiue during the run
142 time of the pwm utility.</para>
143 </refsect2>
144 <refsect2>
145 <title>Fields</title>
146 <para>The following entry fields are supported:</para>
147 <table xml:id="field-table">
148 <title>Fields and their identifiers</title>
149 <tgroup cols="2" align="left" colsep="1" rowsep="1">
150 <thead>
151 <row>
152 <entry>Field</entry>
153 <entry>Field Identifier</entry>
154 </row>
155 </thead>
156 <tbody>
157 <row>
158 <entry>Group</entry>
159 <entry>group</entry>
160 </row>
161 <row>
162 <entry>Title</entry>
163 <entry>title</entry>
164 </row>
165 <row>
166 <entry>Username</entry>
167 <entry>username</entry>
168 </row>
169 <row>
170 <entry>Password</entry>
171 <entry>password</entry>
172 </row>
173 <row>
174 <entry>Notes</entry>
175 <entry>notes</entry>
176 </row>
177 <row>
178 <entry>URL</entry>
179 <entry>url</entry>
180 </row>
181 <row>
182 <entry>Creation Time</entry>
183 <entry>ctime</entry>
184 </row>
185 <row>
186 <entry>Modification Time</entry>
187 <entry>mtime</entry>
188 </row>
189 </tbody>
190 </tgroup>
191 </table>
192 <para>Other, existing fields specified by the PasswordSafe file format
193 will be preserved but cannot be displayed or modified.</para>
194 </refsect2>
195 <refsect2>
196 <title>Commands</title>
197 <para>Each command must appear on a seperate line terminated by a newline
198 character. The command and its arguments are seperated by whitespace,
199 i.e. one or more space or tab characters. If an argument contains
200 whitespace characters it must either be quoted by encosing it in single
201 or double quote characters or each whitespace character must be preceded
202 by a backslash character. Arguments quoted with a single or double quote
203 character preserve the literal values of all characters with the
204 exception of the backslash character which can be used to escape the
205 respective quoting character. Two consecutive backslash characters yield
206 a literal backslash within both quoted and unquoted arguments. A line
207 must not end in a single backslash character, any other backslash
208 characters are ignored.</para>
209 <para>If an error occurrs while parsing or executing a command,
210 <command>pwm</command> will terminate when running in non-interactive
211 mode. In interactive mode it will print an error message and prompt the
212 user for the next command. The following commands are supported:</para>
213 <variablelist>
214 <varlistentry>
215 <term>List entries</term>
216 <listitem>
217 <cmdsynopsis>
218 <command>list</command>
219 <arg choice="opt" rep="repeat">
220 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
221 </arg>
222 </cmdsynopsis>
223 <cmdsynopsis>
224 <command>ls</command>
225 <arg choice="opt" rep="repeat">
226 <replaceable>field</replaceable>~<replaceable>regex</replaceable>
227 </arg>
228 <sbr/>
229 </cmdsynopsis>
230 <para>List password database entries. If one or more filter
231 expressions are specified, limit the displayed entries to those
232 whose <replaceable>field</replaceable> content matches the extended
233 regular expression <replaceable>regex</replaceable>.</para>
234 </listitem>
235 </varlistentry>
236 <varlistentry>
237 <term>Create entry</term>
238 <listitem>
239 <cmdsynopsis>
240 <command>create</command>
241 <arg choice="opt" rep="repeat">
242 <replaceable>field</replaceable>=<replaceable>value</replaceable>
243 </arg>
244 </cmdsynopsis>
245 <cmdsynopsis>
246 <command>c</command>
247 <arg choice="opt" rep="repeat">
248 <replaceable>field</replaceable>=<replaceable>value</replaceable>
249 </arg>
250 <sbr/>
251 </cmdsynopsis>
252 <para>Create a new entry assigning each given
253 <replaceable>field</replaceable> to the corresponsing
254 <replaceable>value</replaceable>.</para>
255 <para>If no fields are specified in interactive mode,
256 <command>pwm</command> will prompt the user for the content of
257 each field.</para>
258 </listitem>
259 </varlistentry>
260 <varlistentry>
261 <term>Modify entry</term>
262 <listitem>
263 <cmdsynopsis>
264 <command>modify</command>
265 <arg choice="plain">
266 <replaceable>id</replaceable>
267 </arg>
268 <arg choice="opt" rep="repeat">
269 <replaceable>field</replaceable>=<replaceable>value</replaceable>
270 </arg>
271 </cmdsynopsis>
272 <cmdsynopsis>
273 <command>m</command>
274 <arg choice="plain">
275 <replaceable>id</replaceable>
276 </arg>
277 <arg choice="opt" rep="repeat">
278 <replaceable>field</replaceable>=<replaceable>value</replaceable>
279 </arg>
280 <sbr/>
281 </cmdsynopsis>
282 <para>Modify an existing entry identified by
283 <replaceable>id</replaceable> assigning each given
284 <replaceable>field</replaceable> to the corresponsing
285 <replaceable>value</replaceable>.</para>
286 <para>If no fields are specified and <command>pwm</command> is
287 running in interactive mode, it will prompt the user for the
288 content of each field, allowing him to edit any previous
289 content.</para>
290 </listitem>
291 </varlistentry>
292 <varlistentry>
293 <term>Remove entry</term>
294 <listitem>
295 <cmdsynopsis>
296 <command>remove</command>
297 <arg choice="plain">
298 <replaceable>id</replaceable>
299 </arg>
300 </cmdsynopsis>
301 <cmdsynopsis>
302 <command>rm</command>
303 <arg choice="plain">
304 <replaceable>id</replaceable>
305 </arg>
306 <sbr/>
307 </cmdsynopsis>
308 <para>Remove an existing entry identified by
309 <replaceable>id</replaceable>.</para>
310 </listitem>
311 </varlistentry>
312 <varlistentry>
313 <term>Display entry fields</term>
314 <listitem>
315 <cmdsynopsis>
316 <command>show</command>
317 <arg choice="plain">
318 <replaceable>id</replaceable>
319 </arg>
320 <arg choice="opt" rep="repeat">
321 <replaceable>field</replaceable>
322 </arg>
323 </cmdsynopsis>
324 <cmdsynopsis>
325 <command>s</command>
326 <arg choice="plain">
327 <replaceable>id</replaceable>
328 </arg>
329 <arg choice="opt" rep="repeat">
330 <replaceable>field</replaceable>
331 </arg>
332 <sbr/>
333 </cmdsynopsis>
334 <para>Display each <replaceable>field</replaceable> of the entry
335 identified by <replaceable>id</replaceable>. If no field is
336 specified, display all fields except the password field.</para>
337 </listitem>
338 </varlistentry>
339 <varlistentry>
340 <term>Pipe entry fields to an external command</term>
341 <listitem>
342 <cmdsynopsis>
343 <command>pipe</command>
344 <arg choice="plain">
345 <replaceable>id</replaceable>
346 </arg>
347 <arg choice="plain" rep="repeat">
348 <replaceable>field</replaceable>
349 </arg>
350 <arg choice="plain">
351 <replaceable>command</replaceable>
352 </arg>
353 </cmdsynopsis>
354 <cmdsynopsis>
355 <command>p</command>
356 <arg choice="plain">
357 <replaceable>id</replaceable>
358 </arg>
359 <arg choice="plain" rep="repeat">
360 <replaceable>field</replaceable>
361 </arg>
362 <arg choice="plain">
363 <replaceable>command</replaceable>
364 </arg>
365 <sbr/>
366 </cmdsynopsis>
367 <para>Pipe the content of each given
368 <replaceable>field</replaceable> of the entry identified by id to
369 command which must be a single argument. The command is executed by
370 invoking the <command>sh</command> utility with the <arg>-c</arg>
371 option and <replaceable>command</replaceable> as its option
372 argument, thus special care should be applied to quoting command.
373 See the <citerefentry><refentrytitle>sh</refentrytitle>
374 <manvolnum>1</manvolnum></citerefentry> manual page for
375 details.</para>
376 </listitem>
377 </varlistentry>
378 <varlistentry>
379 <term>Create empty group</term>
380 <listitem>
381 <cmdsynopsis>
382 <command>creategroup</command>
383 <arg choice="plain">
384 <replaceable>name</replaceable>
385 </arg>
386 </cmdsynopsis>
387 <cmdsynopsis>
388 <command>cg</command>
389 <arg choice="plain">
390 <replaceable>name</replaceable>
391 </arg>
392 <sbr/>
393 </cmdsynopsis>
394 <para>Create a new empty group named
395 <replaceable>name</replaceable>.</para>
396 <para>In interactive-mode the <replaceable>name</replaceable>
397 argument is optional, if it is not specified <command>pwm</command>
398 will prompt the user for it.</para>
399 </listitem>
400 </varlistentry>
401 <varlistentry>
402 <term>Remove empty group</term>
403 <listitem>
404 <cmdsynopsis>
405 <command>removegroup</command>
406 <arg choice="plain">
407 <replaceable>name</replaceable>
408 </arg>
409 </cmdsynopsis>
410 <cmdsynopsis>
411 <command>rg</command>
412 <arg choice="plain">
413 <replaceable>name</replaceable>
414 </arg>
415 <sbr/>
416 </cmdsynopsis>
417 <para>Remove the empty group named
418 <replaceable>name</replaceable>.</para>
419 </listitem>
420 </varlistentry>
421 <varlistentry>
422 <term>Generate a random password</term>
423 <listitem>
424 <cmdsynopsis>
425 <command>generatepassword</command>
426 <arg choice="opt">
427 <replaceable>id</replaceable>
428 </arg>
429 <arg choice="opt">
430 len=<replaceable>n</replaceable>
431 </arg>
432 <arg choice="opt" rep="repeat">
433 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
434 </arg>
435 <arg choice="opt" rep="repeat">
436 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
437 </arg>
438 </cmdsynopsis>
439 <cmdsynopsis>
440 <command>gp</command>
441 <arg choice="opt">
442 <replaceable>id</replaceable>
443 </arg>
444 <arg choice="opt">
445 len=<replaceable>n</replaceable>
446 </arg>
447 <arg choice="opt" rep="repeat">
448 chars=<replaceable>n</replaceable>:<replaceable>chars</replaceable>
449 </arg>
450 <arg choice="opt" rep="repeat">
451 charclass=<replaceable>n</replaceable>:<replaceable>class</replaceable>
452 </arg>
453 <sbr/>
454 </cmdsynopsis>
455 <para>Randomly generate a new password according to the specified
456 constraints. The <literal>len</literal> argument sets the length of
457 the generated password to <replaceable>n</replaceable> characters.
458 The <literal>chars</literal> argument constrains the password to
459 <replaceable>n</replaceable> from the set of characters
460 <replaceable>chars</replaceable>. Similarly, the
461 <literal>charclass</literal> argument to
462 <replaceable>n</replaceable> characters from the extended regular
463 expression character class <replaceable>class</replaceable>.
464 Multiple <literal>char</literal> and <literal>charclass</literal>
465 arguments may be specified, in which case the generated passwords
466 match all of them.</para>
467 </listitem>
468 </varlistentry>
469 <varlistentry>
470 <term>Change the master password</term>
471 <listitem>
472 <cmdsynopsis>
473 <command>changepassword</command>
474 </cmdsynopsis>
475 <cmdsynopsis>
476 <command>ch</command>
477 <sbr/>
478 </cmdsynopsis>
479 <para>Change the master password.</para>
480 </listitem>
481 </varlistentry>
482 <varlistentry>
483 <term>Display help text</term>
484 <listitem>
485 <cmdsynopsis>
486 <command>help</command>
487 <arg choice="opt">
488 <replaceable>command</replaceable>
489 </arg>
490 </cmdsynopsis>
491 <cmdsynopsis>
492 <command>h</command>
493 <arg choice="opt">
494 <replaceable>command</replaceable>
495 </arg>
496 <sbr/>
497 </cmdsynopsis>
498 <para>Display a summary of all commands or usage information for
499 the specified <replaceable>command</replaceable>.</para>
500 </listitem>
501 </varlistentry>
502 <varlistentry>
503 <term>Show metadata information</term>
504 <listitem>
505 <cmdsynopsis>
506 <command>info</command>
507 </cmdsynopsis>
508 <cmdsynopsis>
509 <command>i</command>
510 <sbr/>
511 </cmdsynopsis>
512 <para>Display metadata information such as the user who last wrote
513 to the database, the time when the database was last written to,
514 and the host on which the password database was last written
515 to.</para>
516 </listitem>
517 </varlistentry>
518 <varlistentry>
519 <term>Display status messages</term>
520 <listitem>
521 <cmdsynopsis>
522 <command>status</command>
523 </cmdsynopsis>
524 <cmdsynopsis>
525 <command>t</command>
526 <sbr/>
527 </cmdsynopsis>
528 <para>Redisplay any error message from the previous command and
529 whether there are unsaved changes.</para>
530 </listitem>
531 </varlistentry>
532 <varlistentry>
533 <term>Write database</term>
534 <listitem>
535 <cmdsynopsis>
536 <command>write</command>
537 </cmdsynopsis>
538 <cmdsynopsis>
539 <command>w</command>
540 <sbr/>
541 </cmdsynopsis>
542 <para>Write all changes back to the password database.</para>
543 </listitem>
544 </varlistentry>
545 <varlistentry>
546 <term>Quit</term>
547 <listitem>
548 <cmdsynopsis>
549 <command>quit</command>
550 </cmdsynopsis>
551 <cmdsynopsis>
552 <command>q</command>
553 </cmdsynopsis>
554 <cmdsynopsis>
555 <keysym>end-of-file</keysym>
556 <sbr/>
557 </cmdsynopsis>
558 <para>Quit <command>pwm</command>. If running in interactive mode
559 and there are unsaved changes, <command>pwm</command> will not
560 terminate but display a warning message. If the quit command is
561 invoked twice consecutively, <command>pwm</command> will discard
562 unsaved changes and terminate.</para>
563 </listitem>
564 </varlistentry>
565 <varlistentry>
566 <term>Quit and discard unsaved changes</term>
567 <listitem>
568 <cmdsynopsis>
569 <command>Quit</command>
570 </cmdsynopsis>
571 <cmdsynopsis>
572 <command>Q</command>
573 <sbr/>
574 </cmdsynopsis>
575 <para>Quit <command>pwm</command> and discard any unsaved changes
576 without a warning.</para>
577 </listitem>
578 </varlistentry>
579 </variablelist>
580 </refsect2>
581 </refsect1>
582 <refsect1>
583 <title>File Format</title>
584 <para>The canonical description of the file format is included with the
585 distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle>
586 <manvolnum>1</manvolnum></citerefentry> utility.</para>
587 </refsect1>
588 <refsect1>
589 <title>Environment Variables</title>
590 <variablelist>
591 <varlistentry>
592 <term>
593 <literal>LANG</literal>
594 </term>
595 <term>
596 <literal>LC_ALL</literal>
597 </term>
598 <listitem>
599 <para>See <citerefentry><refentrytitle>locale</refentrytitle>
600 <manvolnum>5</manvolnum></citerefentry></para>
601 </listitem>
602 </varlistentry>
603 <varlistentry>
604 <term>
605 <literal>LOGNAME</literal>
606 </term>
607 <listitem>
608 <para>The name of the logged in user which is recorded when writing
609 the password database</para>
610 </listitem>
611 </varlistentry>
612 </variablelist>
613 </refsect1>
614 <refsect1>
615 <title>Exit Status</title>
616 <para>The following exit values are returned:</para>
617 <variablelist>
618 <varlistentry>
619 <term>0</term>
620 <listitem>
621 <para>Command successfully executed.</para>
622 </listitem>
623 </varlistentry>
624 <varlistentry>
625 <term>1</term>
626 <listitem>
627 <para>An unspecified error has occured.</para>
628 </listitem>
629 </varlistentry>
630 <varlistentry>
631 <term>2</term>
632 <listitem>
633 <para>Invalid command line options were specified.</para>
634 </listitem>
635 </varlistentry>
636 </variablelist>
637 </refsect1>
638 <refsect1>
639 <title>Asynchronous Events</title>
640 <variablelist>
641 <varlistentry>
642 <term><literal>SIGINT</literal></term>
643 <term><literal>SIGHUP</literal></term>
644 <term><literal>SIGTERM</literal></term>
645 <listitem>
646 <para>If there are changes since the database was last written and
647 <command>pwm</command> is running in interactive mode, it
648 automatically writes a copy of the current database to the file
649 <filename>~/.pwm/autosave.psafe3</filename> which may be used for
650 recovery later.</para>
651 </listitem>
652 </varlistentry>
653 </variablelist>
654 </refsect1>
655 <refsect1>
656 <title>Files</title>
657 <variablelist>
658 <varlistentry>
659 <term><filename>~/.pwm/pwm.psafe3</filename></term>
660 <listitem>
661 <para>default password database</para>
662 </listitem>
663 </varlistentry>
664 <varlistentry>
665 <term><filename>~/.pwm/autosave.psafe3</filename></term>
666 <listitem>
667 <para>automatic copy of the password database after receiving a fatal
668 signal in interactive mode</para>
669 </listitem>
670 </varlistentry>
671 </variablelist>
672 </refsect1>
673 <refsect1>
674 <title>See Also</title>
675 <para><citerefentry><refentrytitle>pwsafe</refentrytitle>
676 <manvolnum>1</manvolnum></citerefentry>,
677 <citerefentry><refentrytitle>sh</refentrytitle>
678 <manvolnum>1</manvolnum></citerefentry>,
679 <citerefentry><refentrytitle>locale</refentrytitle>
680 <manvolnum>5</manvolnum></citerefentry>,
681 <citerefentry><refentrytitle>regex</refentrytitle>
682 <manvolnum>5</manvolnum></citerefentry>,
683 <link xlink:href="https://pwsafe.org/"/></para>
684 </refsect1>
685 </refentry>