Mercurial > projects > pwm
changeset 1:55281f14dc9b
Add README file and manpage
author | Guido Berhoerster <guido+pwm@berhoerster.name> |
---|---|
date | Fri, 03 Feb 2017 16:11:58 +0100 |
parents | a7e41e1a79c8 |
children | 5cd0debdb7d8 |
files | Makefile README docbook-update-source-data.xsl pwm.1.xml |
diffstat | 4 files changed, 648 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/Makefile Thu Jan 19 22:39:51 2017 +0100 +++ b/Makefile Fri Feb 03 16:11:58 2017 +0100 @@ -44,10 +44,34 @@ PAX := pax GZIP := gzip SED := sed +XSLTPROC := xsltproc +DOCBOOK5_MANPAGES_STYLESHEET = http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl +DOCBOOK5_MANPAGES_FLAGS = --stringparam man.authors.section.enabled 0 \ + --stringparam man.copyright.section.enabled 0 + +define generate-manpage-rule = +$(addsuffix .%,$(basename $1)): $(addsuffix .%.xml,$(basename $(firstword $1))) docbook-update-source-data.xsl + $$(XSLTPROC) \ + --xinclude \ + --stringparam package $$(PACKAGE) \ + --stringparam version $$(VERSION) \ + docbook-update-source-data.xsl $$< | \ + $$(XSLTPROC) \ + --xinclude \ + --output $(firstword $1) \ + $$(DOCBOOK5_MANPAGES_FLAGS) \ + $$(DOCBOOK5_MANPAGES_STYLESHEET) \ + - + for alias in $(wordlist 2,$(words $1),$1); do \ + ln -sf $(notdir $(firstword $1)) $$$$alias; \ + done +endef DESTDIR ?= prefix ?= /usr/local bindir ?= $(prefix)/bin +datadir ?= $(prefix)/share +mandir ?= $(datadir)/man OS_NAME := $(shell uname -s) OS_RELEASE := $(shell uname -r) @@ -101,11 +125,13 @@ tok.o \ util.o +MANPAGES = pwm.1 + .DEFAULT_TARGET = all .PHONY: all clean clobber dist install -all: $(PACKAGE) +all: $(PACKAGE) $(MANPAGES) XCPPFLAGS = -DPACKAGE=\"$(PACKAGE)\" \ -DVERSION=\"$(VERSION)\" @@ -146,15 +172,26 @@ $(PACKAGE): $(OBJS) $(LINK.o) $^ $(LDLIBS) -o $@ +$(eval $(call generate-manpage-rule,$(MANPAGES))) + %.o: %.c $(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d $(COMPILE.c) -o $@ $< install: $(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)" + for manpage in $(MANPAGES); do \ + if [ -L $${manpage} ]; then \ + $(INSTALL.link) $${manpage} \ + "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \ + else \ + $(INSTALL.data) $${manpage} \ + "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \ + fi \ + done clean: - rm -f $(PACKAGE) $(OBJS) + rm -f $(PACKAGE) $(OBJS) $(MANPAGES) clobber: clean rm -f $(patsubst %.o,%.d,$(OBJS))
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README Fri Feb 03 16:11:58 2017 +0100 @@ -0,0 +1,107 @@ +pwm +=== + +Description +----------- + +The pwm utility is a password manager which stores passwords and associated +metadata in an encrypted database protected by a master password. It has a +text-based user interface and can be used both interactively and +non-interactively. The database uses the PasswordSafe database format +version 3 and is thus compatible with other password managers using this +format. + +Build Instructions +------------------ + +pwm requires a POSIX:2004 compatible operating system, it has been tested to +work on Linux distributions, FreeBSD, NetBSD, OpenBSD, Solaris and +Illumos-derived distributions. The following tools and shared libraries are +required to build pwm: + +- GNU make >= 3.81 +- GNU or BSD install +- libtecla >= 1.6.0 +- libpws >= 1.0.0 + +Rebuilding the man pages additionally requires the xsltproc tool from libxml2. + +Before building pwm check the commented macros in the Makefile for any +macros you may need to override depending on the used toolchain and operating +system. + +By default, all files will be installed under the "/usr/local" directory, a +different installation path prefix can be set via the `prefix` macro. In +addition, a second path prefix can be specified via the `DESTDIR` macro which +will be prepended to any path, incuding the `prefix` macro path prefix. In +contrast to `prefix`, the path specified via the `DESTDIR` macro will only be +prepended to paths during installation and not be used for constructing +internal paths. + +The following instructions assume that `make` is GNU make, on some platforms +it may be installed under a different name or a non-default path. In order to +start the build process run `make all`. After a successful build, run `make +install` to install the program, any associated data files and the +documentation. + +Previously built binaries, object files, generated data files and +documentation can be removed by running `make clean`, any additional, +generated files which are not removed by the `clean` target can be removed by +running `make clobber`. + +Contact +------- + +Please send any feedback, translations or bug reports via email to +<guido+pwm@berhoerster.name>. + +Bug Reports +----------- + +When sending bug reports, please always mention the exact version of pwm +with which the issue occurs as well as the version of the operating system you +are using and make sure that you provide sufficient information to reproduce +the issue and include any input, output, any error messages. + +In case of build issues, please also specify the implementations and versions +of the tools and shared libraries used to build the program, in particular the +compiler. + +In case of crashes, please generate a stack trace with a suitable debugger +such as gdb, lldb, dbx, or debug after a crash has occurred either by +examining the resulting core file or by running the program from the debugger +and attach it to the bug report. In order to generate a meaningful stack +trace the program as well as any dynamically linked libraries need to be built +with debugging information, see the documentation of the used compiler for the +required compiler flags. If any of the dynamically linked shared libraries do +not contain debugging information, please either install debugging information +for these libraries using mechanisms provided by your operating system or +rebuild the libraries accordingly. Please refer to the documentation of the +debugger for detailed instructions on generating backtraces. + +License +------- + +Except otherwise noted, all files are Copyright (C) 2017 Guido Berhoerster and +distributed under the following license terms: + +Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docbook-update-source-data.xsl Fri Feb 03 16:11:58 2017 +0100 @@ -0,0 +1,29 @@ +<?xml version="1.0"?> +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:db="http://docbook.org/ns/docbook" + xmlns="http://docbook.org/ns/docbook" + exclude-result-prefixes="xsl db"> + + <xsl:param name="package" select="''" /> + <xsl:param name="version" select="''" /> + + <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or + @class = 'version']"/> + + <xsl:template match="db:refmeta"> + <xsl:copy> + <xsl:apply-templates/> + <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo> + <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo> + </xsl:copy> + </xsl:template> + + <xsl:template match="@*|node()"> + <xsl:copy> + <xsl:apply-templates select="@*|node()"/> + </xsl:copy> + </xsl:template> + +</xsl:stylesheet>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pwm.1.xml Fri Feb 03 16:11:58 2017 +0100 @@ -0,0 +1,473 @@ +<?xml version="1.0"?> +<!-- + +Copyright (C) 2017 Guido Berhoerster <guido+pwm@berhoerster.name> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en"> + <info> + <author> + <personname> + <firstname>Guido</firstname> + <surname>Berhoerster</surname> + </personname> + <email>guido+pwm@berhoerster.name</email> + <personblurb/> + </author> + <date>3 February, 2017</date> + </info> + <refmeta> + <refentrytitle>pwm</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source"/> + <refmiscinfo class="version"/> + <refmiscinfo class="manual">User Commands</refmiscinfo> + </refmeta> + <refnamediv> + <refname>pwm</refname> + <refpurpose>password manager</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>pwm</command> + <arg choice="opt"> + <option>-P</option> + <replaceable>password_file</replaceable> + </arg> + <arg choice="opt"> + <replaceable>database_file</replaceable> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para>The <command>pwm</command> utility is a password manager which + stores passwords and associated metadata in an encrypted database protected + by a master password. It offers both a text-based user interface for + interactive use as well as a non-interactive mode. The database uses the + PasswordSafe database version 3 file format and thus provides + interoperabity with other password managers using the same format.</para> + <para>After opening an existing database or creating a new one, + <command>pwm</command> provides commands to create, modify, delete, and + display password database entries which may be organized in groups. The + contents of a field of a given entry can also be piped to an external + command, e.g. in order to copy the content of the username or password + field of an entry to the clipboard.</para> + <para>If specified, <command>pwm</command> will open or create + <replaceable>database_file</replaceable> instead of the user's default + database.</para> + <para><command>pwm</command> must be run with a locale which uses the UTF-8 + character encoding.</para> + <refsect2> + <title>Output format</title> + <para>The <command>show</command> command displays selected fields by + printing the field name followed by a colon, one or more space characters + and the field's verbatim content to the standard output stream. Field + values may contain newlines, non-printable and/or control + characters.</para> + <para>The <command>pipe</command> prints the verbatim field content to the + standard input stream of the given command.</para> + <para>Error messages are printed to the standard error stream.</para> + </refsect2> + </refsect1> + <refsect1> + <title>Options</title> + <para>The following options are supported:</para> + <variablelist> + <varlistentry> + <term> + <option>-P</option> + <replaceable>password_file</replaceable> + </term> + <listitem> + <para>Read the master password from the first line of + <replaceable>password_file</replaceable>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Usage</title> + <para>If stdin is connected to a terminal pwm will run in interactive mode + and prompt the user for the master password unless + <replaceable>password_file</replaceable> is specified via the + <option>-P</option> option. After successfully opening the password + database the user will be prompted for a command.</para> + <para>When running in non-interactive mode a file containing the master + pasword must be specified via the <option>-P</option> option and after + successfully opening the password database, pwm will execute commands read + from stdin until either an error occurrs or end-of-file is reached.</para> + <para><command>pwm</command> operates on a copy of the password database + in memory, any changes must be explicitly written back to the database + using the write command.</para> + <refsect2> + <title>IDs</title> + <para>Database entries are referred to by an ID value which is a + positive integer value that is guaranteed to be unqiue during the run + time of the pwm utility.</para> + </refsect2> + <refsect2> + <title>Fields</title> + <para>The following entry fields are supported: + <simplelist type="vert"> + <member>group</member> + <member>title</member> + <member>username</member> + <member>password</member> + <member>notes</member> + <member>url</member> + </simplelist> + </para> + <para>Other, existing fields specified by the PasswordSafe file format + will be preserved but cannot be displayed or modified.</para> + </refsect2> + <refsect2> + <title>Commands</title> + <para>Each command must appear on a seperate line terminated by a newline + character. The command and its arguments are seperated by whitespace, + i.e. one or more space or tab characters. If an argument contains + whitespace characters it must either be quoted by encosing it in single + or double quote characters or each whitespace character must be preceded + by a backslash character. Arguments quoted with a single or double quote + character preserve the literal values of all characters with the + exception of the backslash character which can be used to escape the + respective quoting character. Two consecutive backslash characters yield + a literal backslash within both quoted and unquoted arguments. A line + must not end in a single backslash character, any other backslash + characters are ignored.</para> + <para>If an error occurrs while parsing or executing a command, + <command>pwm</command> will terminate when running in non-interactive + mode. In interactive mode it will print an error message and prompt the + user for the next command. The following commands are supported:</para> + <variablelist> + <varlistentry> + <term>List entries</term> + <listitem> + <cmdsynopsis> + <command>list</command> + </cmdsynopsis> + <cmdsynopsis> + <command>ls</command> + <sbr/> + </cmdsynopsis> + <para>List all password database entries.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Create entry</term> + <listitem> + <cmdsynopsis> + <command>create</command> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable>=<replaceable>value</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>c</command> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable>=<replaceable>value</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Create a new entry assigning each given + <replaceable>field</replaceable> to the corresponsing + <replaceable>value</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Modify entry</term> + <listitem> + <cmdsynopsis> + <command>modify</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable>=<replaceable>value</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>m</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable>=<replaceable>value</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Modify an existing entry identified by + <replaceable>id</replaceable> assigning each given + <replaceable>field</replaceable> to the corresponsing + <replaceable>value</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Remove entry</term> + <listitem> + <cmdsynopsis> + <command>remove</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>rm</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Remove an existing entry identified by + <replaceable>id</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Display entry fields</term> + <listitem> + <cmdsynopsis> + <command>show</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>s</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="opt" rep="repeat"> + <replaceable>field</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Display each <replaceable>field</replaceable> of the entry + identified by <replaceable>id</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Pipe entry fields to an external command</term> + <listitem> + <cmdsynopsis> + <command>pipe</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="plain" rep="repeat"> + <replaceable>field</replaceable> + </arg> + <arg choice="plain"> + <replaceable>command</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>p</command> + <arg choice="plain"> + <replaceable>id</replaceable> + </arg> + <arg choice="plain" rep="repeat"> + <replaceable>field</replaceable> + </arg> + <arg choice="plain"> + <replaceable>command</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Pipe the content of each given + <replaceable>field</replaceable> of the entry identified by id to + command which must be a single argument. The command is executed by + invoking the <command>sh</command> utility with the <arg>-c</arg> + option and <replaceable>command</replaceable> as its option + argument, thus special care should be applied to quoting command. + See the <citerefentry><refentrytitle>sh</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> manual page for + details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Create empty group</term> + <listitem> + <cmdsynopsis> + <command>creategroup</command> + <arg choice="plain"> + <replaceable>name</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>cg</command> + <arg choice="plain"> + <replaceable>name</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Create a new empty group named + <replaceable>name</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Remove empty group</term> + <listitem> + <cmdsynopsis> + <command>removegroup</command> + <arg choice="plain"> + <replaceable>name</replaceable> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>rg</command> + <arg choice="plain"> + <replaceable>name</replaceable> + </arg> + <sbr/> + </cmdsynopsis> + <para>Remove the empty group named + <replaceable>name</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Change the master password</term> + <listitem> + <cmdsynopsis> + <command>changepassword</command> + </cmdsynopsis> + <cmdsynopsis> + <command>ch</command> + <sbr/> + </cmdsynopsis> + <para>Change the master password.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Display help text</term> + <listitem> + <cmdsynopsis> + <command>help</command> + </cmdsynopsis> + <cmdsynopsis> + <command>h</command> + <sbr/> + </cmdsynopsis> + <para>Display a list of all commands and a short help text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Write database</term> + <listitem> + <cmdsynopsis> + <command>write</command> + </cmdsynopsis> + <cmdsynopsis> + <command>w</command> + <sbr/> + </cmdsynopsis> + <para>Write all changes back to the password database.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Quit</term> + <listitem> + <cmdsynopsis> + <command>quit</command> + </cmdsynopsis> + <cmdsynopsis> + <command>q</command> + <sbr/> + </cmdsynopsis> + <para>Quit <command>pwm</command>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + <refsect1> + <title>File Format</title> + <para>The canonical description of the file format is included with the + distribution of the <citerefentry><refentrytitle>pwsafe</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> utility.</para> + </refsect1> + <refsect1> + <title>Environment Variables</title> + <variablelist> + <varlistentry> + <term> + <literal>LANG</literal> + </term> + <term> + <literal>LC_ALL</literal> + </term> + <listitem> + <para>See <citerefentry><refentrytitle>locale</refentrytitle> + <manvolnum>5</manvolnum></citerefentry></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Exit Status</title> + <para>The following exit values are returned:</para> + <variablelist> + <varlistentry> + <term>0</term> + <listitem> + <para>Command successfully executed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>1</term> + <listitem> + <para>An unspecified error has occured.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>2</term> + <listitem> + <para>Invalid command line options were specified.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Files</title> + <variablelist> + <varlistentry> + <term><filename>~/.pwm/pwm.psafe3</filename></term> + <listitem> + <para>default password database</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>See Also</title> + <para><citerefentry><refentrytitle>pwsafe</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sh</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale</refentrytitle> + <manvolnum>5</manvolnum></citerefentry>, + <link xlink:href="https://pwsafe.org/"/></para> + </refsect1> +</refentry>