# HG changeset patch # User Guido Berhoerster # Date 1486134718 -3600 # Node ID 55281f14dc9b79f634f3f7ebba82e0c7cd0315c7 # Parent a7e41e1a79c8e522c175b3de5aedc8e88f292950 Add README file and manpage diff -r a7e41e1a79c8 -r 55281f14dc9b Makefile --- 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)) diff -r a7e41e1a79c8 -r 55281f14dc9b README --- /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 +. + +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 + +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. diff -r a7e41e1a79c8 -r 55281f14dc9b docbook-update-source-data.xsl --- /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 @@ + + + + + + + + + + + + + + + + + + + + + + + diff -r a7e41e1a79c8 -r 55281f14dc9b pwm.1.xml --- /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 @@ + + + + + + + Guido + Berhoerster + + guido+pwm@berhoerster.name + + + 3 February, 2017 + + + pwm + 1 + + + User Commands + + + pwm + password manager + + + + pwm + + + password_file + + + database_file + + + + + Description + The pwm 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. + After opening an existing database or creating a new one, + pwm 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. + If specified, pwm will open or create + database_file instead of the user's default + database. + pwm must be run with a locale which uses the UTF-8 + character encoding. + + Output format + The show 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. + The pipe prints the verbatim field content to the + standard input stream of the given command. + Error messages are printed to the standard error stream. + + + + Options + The following options are supported: + + + + + password_file + + + Read the master password from the first line of + password_file. + + + + + + Usage + If stdin is connected to a terminal pwm will run in interactive mode + and prompt the user for the master password unless + password_file is specified via the + option. After successfully opening the password + database the user will be prompted for a command. + When running in non-interactive mode a file containing the master + pasword must be specified via the 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. + pwm operates on a copy of the password database + in memory, any changes must be explicitly written back to the database + using the write command. + + IDs + 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. + + + Fields + The following entry fields are supported: + + group + title + username + password + notes + url + + + Other, existing fields specified by the PasswordSafe file format + will be preserved but cannot be displayed or modified. + + + Commands + 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. + If an error occurrs while parsing or executing a command, + pwm 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: + + + List entries + + + list + + + ls + + + List all password database entries. + + + + Create entry + + + create + + field=value + + + + c + + field=value + + + + Create a new entry assigning each given + field to the corresponsing + value. + + + + Modify entry + + + modify + + id + + + field=value + + + + m + + id + + + field=value + + + + Modify an existing entry identified by + id assigning each given + field to the corresponsing + value. + + + + Remove entry + + + remove + + id + + + + rm + + id + + + + Remove an existing entry identified by + id. + + + + Display entry fields + + + show + + id + + + field + + + + s + + id + + + field + + + + Display each field of the entry + identified by id. + + + + Pipe entry fields to an external command + + + pipe + + id + + + field + + + command + + + + p + + id + + + field + + + command + + + + Pipe the content of each given + field of the entry identified by id to + command which must be a single argument. The command is executed by + invoking the sh utility with the -c + option and command as its option + argument, thus special care should be applied to quoting command. + See the sh + 1 manual page for + details. + + + + Create empty group + + + creategroup + + name + + + + cg + + name + + + + Create a new empty group named + name. + + + + Remove empty group + + + removegroup + + name + + + + rg + + name + + + + Remove the empty group named + name. + + + + Change the master password + + + changepassword + + + ch + + + Change the master password. + + + + Display help text + + + help + + + h + + + Display a list of all commands and a short help text. + + + + Write database + + + write + + + w + + + Write all changes back to the password database. + + + + Quit + + + quit + + + q + + + Quit pwm. + + + + + + + File Format + The canonical description of the file format is included with the + distribution of the pwsafe + 1 utility. + + + Environment Variables + + + + LANG + + + LC_ALL + + + See locale + 5 + + + + + + Exit Status + The following exit values are returned: + + + 0 + + Command successfully executed. + + + + 1 + + An unspecified error has occured. + + + + 2 + + Invalid command line options were specified. + + + + + + Files + + + ~/.pwm/pwm.psafe3 + + default password database + + + + + + See Also + pwsafe + 1, + sh + 1, + locale + 5, + + +